System Requirements and Installation Guide
Introduction
The easiest way to start rotki is to download the packaged binary for your Operating system. Linux, OSX and Windows is supported. To see how to do this go to the next section.
Packaged Binaries
Verifying integrity
Starting with the release of v1.6.2, rotki releases now include the sha512 sum of the packaged binaries. You can download the file containing the hash along with the binary from the release page.
The files containing the hash have the same name as their respective binaries followed by a .sha512
extension.
In order to do the verification of a binary, you have to also download the .sha512
file for it.
In order to proceed with the verification on Linux and OSX, you need to open your terminal and go to the download directory.
On linux:
cd ~/Downloads
sha512sum -c rotki-linux_x86_64-vx.x.x.AppImage.sha512
rotki-linux_x86_64-vx.x.x.AppImage: OK
On OSX:
cd ~/Downloads
shasum -a 512 -c rotki-darwin-vx.x.x.dmg.sha512
rotki-darwin-vx.x.x.dmg: OK
If there is any problem with the checksum verification you should get an error similar to the following:
rotki-linux_x86_64-vx.x.x.AppImage: FAILED
sha512sum: WARNING: 1 computed checksum did NOT match
On Windows you need to first open the Command Prompt
. Once the command prompt is open you need to go
to the Download
directory where the rotki executable and sha512 files were downloaded.:
cd Downloads
certutil -hashfile rotki-win32-vx.x.x.exe SHA512
After successfully running the command you should be able to see the commands output:
SHA512 hash of rotki-win32-v1.6.2.exe:
a3e0d79724460f642245774ba1af4c7116dfde56503d134c688f406afff5339f70a84a0bdb2556bc0785931b11e2447e3ffcd116cdec9e8a50382ec0165788b4
CertUtil: -hashfile command completed successfully.
To verify that the generated hash matches you need to open the rotki-win32-vx.x.x.exe.sha512
with Notepad
or
any other text editor and make sure that the hash there matches the one generated by the certutil command.
Linux
Go to the releases page and download the linux-x64 appimage from the latest release. Or the tar.xz
file. Whichever you prefer.
If you got the appimage you have to give it the executable permission. Do chmod +x rotki-linux_x86_64-vx.x.x.AppImage
replacing the x
with the proper version. And then run it.
If you got the tar, unzip it in a directory of your choice. In the root directory of the unzipped archive there is a rotki
executable. Run it via the terminal to start rotki.
Troubleshooting
If you get a problem when starting the application or during its usage please open an issue in Github and include all logs that can be found in ~/.config/rotki/logs
.
OSX
Homebrew
brew install --cask rotki
Manual installation
Go to the releases page and download the darwin-x64 dmg package from the latest release.
Note
rotki’s minimum supported macOS version is Mojave(10.14). If you can’t upgrade to Mojave(hardware older than 2012) either buy new Mac hardware or switch to Linux or Windows. This does not depend on us. It’s Apple’s policy to force their users buy more hardware.
Click on the dmg installer and when prompted drag the rotki logo to your Applications. This will install the application and once finished you can select rotki from your applications folder and launch it.
If your OSX version does not allow you to open the application you will have to go to your OS settings and insert an exception for rotki to let it run. Here is a guide.
Troubleshooting
If you get a problem when starting the application or during its usage please open an issue in Github and include all logs that can be found in ~/Library/Application Support/rotki/logs
.
Windows
Go to the releases page and download the win32-x64 package from the latest release.
Unzip it in a folder of your choice. In the root directory of the unzipped archive there is a rotki
executable. Double click it to start rotki.
Troubleshooting
If you get “The python backend crashed” or any other error please run the executable via the Command Prompt. Then provide us with the output that is visible in the prompt and this will help us debug your issue.
You should also include all logs that can be found in <WindowsDrive>:\Users\<User>\Roaming\rotki\logs\
(%APPDATA%\rotki\logs
).
Docker
Since v1.11.0 rotki provides official docker images of nightly versions and releases.
Versions up to v1.13.2 report a dev version instead of the actual release. This is due to an issue during the build process.
You can find all the available docker images at DockerHub.
Warning
It is important to keep in mind that is advisable to run the docker image in a secure environment. Such an environment would be for example running the docker image in the host machine and accessing it only via NAT. Under no circumstances should you expose the docker image directly to public or local networks since this can lead to security issues and unauthorized access of your data.
You can get the latest version of rotki by pulling the latest
tag.
This tag always points to the latest rotki release:
docker pull rotki/rotki:latest
To start a container based on the latest rotki image you can run the following:
docker run -d --name rotki \
-p 8084:80 \
-v $HOME/.rotki/data:/data \
-v $HOME/.rotki/logs:/logs \
rotki/rotki:latest
Warning
On Linux the mounted volume folders for data and logs will be
owned by the root
user. If the owner of these folder changes
to some other user than root this will make them inaccessible
by the the container, which can result in 500 errors when
accessing rotki in the container.
If you run into this issue you can fix it by changing the
directory owner back to root
.
This will start a new container that stores the data and logs into a
.rotki
directory under the user’s home directory. You will be able
to find your account data (databases etc) under the .rotki/data
directory. If port 8084 busy on your machine, feel free to choose
any other available port.
At this point the rotki docker container should be running and you
should be able to access rotki frontend, open your browser and go to
it at http://localhost:8084
. You should be able to see the rotki login screen.
Configuring backend in docker
It is possible to change the configuration of the backend in the docker container. You can do so using two different approaches.
The first approach include mounting a config volume:
docker run -d --name rotki \
-p 8084:80 \
-v $HOME/.rotki/data:/data \
-v $HOME/.rotki/logs:/logs \
-v $HOME/.rotki/config:/config \
rotki/rotki:latest
You need to create a rotki_config.json
file and put it inside $HOME/.rotki/config
directory.
{
"loglevel": "info",
"logfromothermodules": true,
"sleep-secs": 22,
"max_size_in_mb_all_logs": 550,
"max_logfiles_num": 3,
"sqlite_instructions": 0,
}
The list above contains all the supported configuration options, but you can also specify only the ones you would like to change. This approach allows you to modify the config and restart the container to apply them.
The second approach is by using environment variables during the container creation:
docker run -d --name rotki \
-p 8084:80 \
-v $HOME/.rotki/data:/data \
-v $HOME/.rotki/logs:/logs \
-e LOGLEVEL=debug
rotki/rotki:latest
The supported environment variables are LOGLEVEL
, LOGFROMOTHERMODDULES
, MAX_SIZE_IN_MB_ALL_LOGS
, MAX_LOGFILES_NUM
and SQLITE_INSTRUCTIONS
. Since these variables are passed during the container creation to change them requires re-creating the container with the new parameters.
Warning
When using both a config file and environment variables, the config file will take precedence.
Time in Profit / Loss Report is in wrong.
To set the timezone in the docker environment you can use the option -e TZ=Timezone
when starting the container:
docker run -d --name rotki \
-p 8084:80 \
-v $HOME/.rotki/data:/data \
-v $HOME/.rotki/logs:/logs \
-e TZ=America/New_York \
rotki/rotki:latest
You can find all TimeZone Databases on Wikipedia: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
Updating to a newer version
When a new rotki version is out there are few steps you need to follow in order to upgrade to a newest version.
First you have to stop the rotki container from running:
docker stop rotki
Then you need to remove the old container:
docker rm rotki
Since your data are stored in volumes in the host machine, deleting the container will not touch your data.
In order to update to the latest version you need to once again pull the latest tag from docker hub:
docker pull rotki/rotki:latest
After the latest image is properly updated on your machine you need to create a new container:
docker run -d --name rotki \
-p 8084:80 \
-v $HOME/.rotki/data:/data \
-v $HOME/.rotki/logs:/logs \
rotki/rotki:latest
Please ensure that the volumes from the previous container are used again. If you don’t use the same volumes, then your old accounts and data will be unavailable.
Docker Compose
If you prefer to use docker compose, a docker-compose.yml template is provided below for convenience.
Using docker over a public network
Since rotki was not designed to run over a public network it is generally advised to avoid directly exposing your rotki instance over public network.
If you still want to access rotki over a public network it is suggested to use at least a proxy with basic authentication as an intermediate layer of security. With this setup anyone that visits your public domain will need to authenticate with the basic auth user and password before accessing rotki’s user interface.
Additionally treafik will be setup to automatically request and setup an SSL certificate to ensure that your connection to your rotki instance is properly encrypted using TLS.
We are going to assume that you have a server provisioned and a domain rotki.example.com
already set to the
server’s IP address.
First we need to create a basic auth user with a password. Use the apache utilities to create a secure
password using bcrypt
for your user.
htpasswd -cB ~/.rotki/.htpasswd user
Then proceed to create an .env
file in the same directory where your docker-compose.yml
will be.
In the env file set your authentication user, the domain and the e-mail of the where you will receive
notification about the status of your domain.
AUTH_USER=username
FQDN=rotki.example.com
LETSENCRYPT_EMAIL=user@example.com
Next you need to create the docker-compose.yml
.
version: "3.10"
services:
proxy:
image: traefik:2.9
restart: always
command:
- "--global.sendAnonymousUsage=false"
- "--providers.docker"
- "--providers.docker.exposedByDefault=false"
- "--entrypoints.web.address=:80"
- "--entrypoints.websecure.address=:443"
- "--certificatesresolvers.le.acme.httpchallenge=true"
- "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
- "--certificatesresolvers.le.acme.email=${LETSENCRYPT_EMAIL}"
- "--certificatesresolvers.le.acme.storage=/etc/acme/acme.json"
ports:
- "80:80"
- "443:443"
networks:
- rotki-net
volumes:
- $HOME/.rotki/.htpasswd:/auth/.htpasswd
- $HOME/.rotki/acme/:/etc/acme/
- /var/run/docker.sock:/var/run/docker.sock:ro
rotki:
environment:
- TZ=Europe/Berlin # TimeZone Databases on Wikipedia: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
image: rotki/rotki:latest
networks:
- rotki-net
volumes:
- $HOME/.rotki/data:/data
- $HOME/.rotki/logs:/logs
labels:
- "traefik.enable=true"
- "traefik.http.services.rotki.loadbalancer.server.port=80"
- "traefik.http.middlewares.redirect.redirectscheme.scheme=https"
- "traefik.http.middlewares.rotki-auth.basicauth.realm=`${AUTH_USER}`"
- "traefik.http.middlewares.rotki-auth.basicauth.usersfile=/auth/.htpasswd"
- "traefik.http.routers.rotki-insecure.rule=Host(`${FQDN}`)"
- "traefik.http.routers.rotki-insecure.middlewares=redirect"
- "traefik.http.routers.rotki.rule=Host(`${FQDN}`)"
- "traefik.http.routers.rotki.middlewares=rotki-auth"
- "traefik.http.routers.rotki.entrypoints=websecure"
- "traefik.http.routers.rotki.tls.certresolver=le"
networks:
rotki-net:
Once the docker-compose.yml
file is saved you will need to run:
docker compose up -d
With this traefik
will act as a proxy with basic authentication that will protect your rotki instance interface
from unauthorized access. When navigating to http://rotki.example.com
you will get a browser popup where you
have to insert the AUTH_USER
and the password you created with htpasswd
.
After passing the base authentication step you will be greeted with the familiar login page of rotki.
Note
As a bonus you should now be able to also access rotki from your mobile phone.
Using docker on a private network
Using Docker Defined Volume:
version: '3.7'
services:
rotki:
environment:
- TZ=America/Chicago # TimeZone Databases on Wikipedia: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
image: rotki/rotki:latest
ports:
- "8084:80" # Container exposes port 80, 8084 can be any port of your choosing.
networks:
- rotki-net
volumes:
- rotki-data:/data
- rotki-logs:/logs
volumes:
rotki-data:
rotki-logs:
networks:
rotki-net:
Using $home (or which ever path to your local data) Defined directed volume:
version: '3.7'
services:
rotki:
environment:
- TZ=America/Chicago # TimeZone Databases on Wikipedia: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
image: rotki/rotki:latest
ports:
- "8084:80" # Container exposes port 80, 8084 can be any port of your choosing.
networks:
- rotki-net
volumes:
- $HOME/.rotki/data:/data
- $HOME/.rotki/logs:/logs
networks:
rotki-net:
Moving the accounts from the desktop application
If for any reason you would like to move your accounts from the rotki application to docker you can do so by copying the data directory of the application to the docker data volume.
You can find where the rotki application data is stored in the Rotki data directory.
To move your existing accounts from the application, you can copy the contents of the application data directory to the data volume mount point.
Assuming that you used the directory from the example, to move a specific account on linux, you have to run:
sudo cp -R ~/.local/share/rotki/data/username ~/.rotki/data/username
This will copy the username
account to the data volume and make it accessible through
the docker container.
Troubleshooting
If you get a problem when starting the application or during its usage
please open an issue in Github and include all logs that can be found
in $HOME/.rotki/logs/rotki.log
or the custom volume you used during
the container creation.
Build from Source
Linux
Make sure you have node.js and pnpm. If you don’t, use your linux distro’s package manager to get them.
rotki uses pnpm v7. To check if you have version 7 of pnpm you can run:
pnpm --version
If you are on an older version of pnpm, you can install it by:
pnpm install -g pnpm@8
# or if you don't have it installed you can
npm install -g pnpm@8
Install electron and any other dependencies by:
cd frontend
pnpm install --frozen-lockfile
Create a new virtual environment with python 3.10 to install all the python dependencies. If you don’t have mkvirtualenv
then check how to get it depending on your distribution. Here is a guide for Ubuntu and here is one for ArchLinux:
mkvirtualenv rotki -p /usr/bin/python3.10
Then install all the python requirements by doing:
pip install -r requirements.txt
If you want to also have the developer requirements in order to develop rotki then do:
pip install -r requirements_dev.txt
Since the electron application is located in a different directory you also need to do:
pip install -e .
If you modified the @rotki/common package you might need to rebuild it. To do this you can go to frontend
and
run pnpm run --filter @rotki/common build
.
After that you can start the application from the frontend
directory by typing pnpm run dev
.
If you don’t want to do the development inside electron or you want to test any non-electron features in your browsers
you can alternatively start pnpm run dev:web
this will start everything except electron. After the vue development
server was finished starting up you should be able to access the url from your browser. Keep in mind that this
works only for localhost access and a proxy might be needed to access it from a different machine.
Packaging
To package the application for your platform you need to run the packaging script. To do so you need to make sure that packaging
and requests
are installed in your virtual environment
pip3 install packaging requests
./package.py --build full
OSX
The tl;dr version is:
- Use a virtual env with Python 3.10.x
- Confirm pip``(pip3) install correctly and up to date
- Get your node under control with ``nvm
. It has been tested with v18
The you will also need VirtualEnv.
Install Homebrew first if not installed yet.
To use Virtualenvwrapper use the following:
$ pip3 install virtualenv
$ pip3 install virtualenvwrapper
And add the following to your shell startup file (e.g. .bashrc, .bash_profile, or .zshrc)
#Virtualenvwrapper settings:
export WORKON_HOME=$HOME/.virtualenvs
export PROJECT_HOME=$HOME/rotki_dev
export VIRTUALENVWRAPPER_PYTHON=/Library/Frameworks/Python.framework/Versions/3.10/bin/python3
export VIRTUALENVWRAPPER_VIRTUALENV=/Library/Frameworks/Python.framework/Versions/3.10/bin/virtualenv
source /Library/Frameworks/Python.framework/Versions/3.10/bin/virtualenvwrapper.sh
And reload shell startup file:
$ source ~/.bash_profile
And activate Python virtual environment:
$ workon rotki
Before using pip3, let´s ensure we have the latest version:
$ pip3 install --upgrade pip
Install all the requirements:
$ pip3 install -r requirements.txt
If you want to also have the developer requirements in order to develop rotki then do:
$ pip3 install -r requirements_dev.txt
Since the electron application is located in a different directory you also need to do:
$ pip3 install -e .
rotki uses Electron <https://electronjs.org>, we need to install it. To do so you need Node.js
and npm
. If you don’t have it use Homebrew to install it:
$ brew install node
rotki uses pnpm v8. To check if you have version * of pnpm you can run:
pnpm --version
If you are on an older version of pnpm, you can install it by:
pnpm install -g pnpm@8
# or if you never installed it before you can
npm install -g pnpm@8
Almost there, we can now install all the Node.js dependencies of the frontend app:
$ cd frontend $ pnpm install –frozen-lockfile
You can now start rotki, still from the frontend
directory:
$ pnpm run dev
Packaging
To package the application for your platform you need to run the packaging script. To do so you need to make sure that packaging
and requests
are installed in your virtual environment
pip3 install packaging requests
./package.py --build full
Note
If you are using an Apple Silicon mac to package rotki, you might come across the following error during the SQLCipher verification step. ImportError: dlopen(/…/lib/python3.9/site-packages/pysqlcipher3/_sqlite3.cpython-39-darwin.so, 0x0002): symbol not found in flat namespace (_ERR_error_string) This is a known problem that does not affect the final binary. You can use SKIP_SQLCIPHER_VERIFICATION ./package.py to build while skipping the verification step.
Windows
This is a guide on how to set up a rotki development environment in Windows from source.
Dependencies
Node & pnpm
Install node.
Install pnpm
:
$ npm install -g pnpm@8
Python
Get python 3.10 (3.10 is required due to some rotki dependencies). Make sure to download the 64-bit version of python if your version of Windows is 64-bit! If you’re unsure of what Windows version you have, you can check in Control Panel -> System and Security -> System.
For some reason python does not always install to the Path variable in Windows. To ensure you have the necessary python directories referenced, go to Control Panel -> System -> Advanced system settings -> Advanced (tab) -> Environment Variables… In the Environment Variables… dialog under “System Variables” open the “Path” variable and ensure that both the root python directory as well as the
\Scripts\
subdirectory are included. If they are not, add them one by one by clicking “New” and then “Browse” and locating the correct directories. NOTE: By default the Windows MSI installer place python in theC:\Users\<username>\AppData\Local\Programs\
directory.To test if you have entered python correctly into the Path variable, open a command prompt and type in
python
then hit Enter. The python cli should run and you should see the python version you installed depicted above the prompt. Press CTRL+Z, then Enter to exit.Note
For some reason in newer versions of Windows typing “python” will actually open the Windows Store – you can fix this by opening “App execution aliases” (search for it via the Windows Search) and toggling off the aliases for python.exe and python3.exe.
Make sure you have pip installed. If your Path environment variable is correctly set up, you can type
pip -V
into a command prompt to check (it should return the version of the installed pip).Make sure you have the latest version of pip installed by executing:
pip install --upgrade pip
Using pip, install virtualenvironment and the virtualenvwrapper-win. See instructions here for installing them on Windows. You can choose to follow the rest of the guide as an example or just read the instructions.
Lastly, make sure you have the Microsoft Visual Studio build tools. For some reason installing the build tools alone won’t work; you’ll need to install the “Desktop development with C++” workload from Visual Studio. To do this, head over to Microsoft’s Website and install Visual Studio. After doing that open up the Visual Studio Installer (can open it from the windows start menu) then click on “Modify” button. Under the “Workloads” tab, select Desktop development with C++ (under the Desktop & Mobile section). Then finally, click on the “modify” button to download and install it. You may need to restart you PC.
Check the troubleshooting guide’s relevant section Microsoft Visual C++ 14.0 is required.
Git
Get latest git.
Downloading source and installing python dependencies
This guide will assume that you want to use git to clone the project into a development directory; if you wish to just download the source from Github as a zip you can do that instead (the zip file has everything in a folder in the format of <project>-<branch>
, so if you download rotki/develop you will get a folder rotki-develop
; you can of course rename this). If you download the source as a zip you can skip to Step 4 below.
Fork the relevant rotki branch into your own account in github.
Open a terminal (command prompt / PowerShell prompt / etc.) in your root development directory (the parent directory of where you will place your rotki development directory).
Clone your forked project into the local directory where you want to build rotki (e.g. if you forked the rokti/develop branch you might clone into
c:\dev\rotki-develop
).
At this point in your local rotki development directory you should have all the same files as they appear in the github page for the rotki branch you chose to download/clone.
Going back to your open terminal, it’s time to set up your python virtual environment (virtualenv).
Recalling the instructions above on how to set up the virtualenv, set one up for rotki (you don’t have to use the name
rotki-develop
):mkvirtualenv rotki-develop
Ensure that you’re in the directory where you downloaded/cloned the rotki source and bind the virtualenv to the directory:
setprojectdir .
If at any time you want to disassociate with the virtual env, you can use the command deactivate
. Whenever you open a new terminal you can now use workon rotki-develop
(if you named your virtualenv something else then use that instead of rotki-develop
) and it should establish the link to the python virtualenv you created and set your working directory to the directory you were in in Step 5. Following the example above, if you open a brand new terminal and type in workon rotki-develop
your terminal prompt should look something like:
(rotki-develop) c:\dev\rotki-develop>
Now it’s time to install all the python requirements. In the open terminal with your virtualenv activated, execute:
pip install -r requirements_dev.txt
Pay close attention to the results of the command. Sometimes modules are reported as successfully installed but in reality the build has failed. You should carefully scroll through the buffer to ensure everything has been built & installed correct.
pip install -e .
You need to download miniupnpc for windows <https://github.com/mrx23dot/miniupnp/releases/download/miniupnpd_2_2_24/miniupnpc_64bit_py39-2.2.24.zip>
After the download, extract the zip contents and copy the miniupnpc.dll to your virtual environment’s Lib > site-packages directory. To locate this directory you can use command:
pip show <any package name from requirements.txt file>
For example, you can use:
pip show cryptography
The Location attribute is where the miniupnpc.dll should be placed (mine was located in the C:\users\<your computer name>\envs\rotki-develop\lib\site-packages).
To make sure that rotki works you can try starting using the following:
python -m rotkehlchen
This should greet you with the following message: rotki REST API server is running at: 127.0.0.1:5042
.
Installing Electron and Running rotki
In your terminal, navigate to your rotki development directory and enter the following commands to install electron and its dependencies:
cd frontend pnpm install --frozen-lockfile
If you get any errors you might need to build the
@rotki/common
library:pnpm run --filter @rotki/common build
At this point, your terminal’s cwd should be
<rotki development directory>\frontend\
and the rotki virtualenv should be activated. You should now be able to start rotki in development mode by executing:pnpm run dev
After the app is built, if everything went well you should see the below text in your terminal and a new electron window that has opened with the rotki app running.
INFO Starting development server...
...
INFO Launching Electron...
2020-XX-XXXX:XX:XX.XXXX: The Python sub-process started on port: XXXX (PID: YYYY)
If you get any errors about missing dependencies, try to install them via npm and run again; consult the troubleshooting section for other errors.
Alternatively, you can also choose to build the application. In order to do so, navigate to your rotki development directory and execute the
package.py
file.:pip3 install packaging requests python .\package.py --build full
Troubleshooting
anyapi-ms-win-crt-runtime missing
If you get anyapi-ms-win-crt-runtime-l1-1-0.dll is missing
error when running python follow this guide to resolve it.
Microsoft Visual C++ 14.0 is required
If you get:
building 'gevent.libev.corecext' extension
error: Microsoft Visual C++ 14.0 is required. Get it with "Microsoft Visual C++ Build Tools": https://visualstudio.microsoft.com/downloads/
Then go here and get the microsoft visual studio build tools and install them. The specific parts of the tools that need to be installed can be seen in this SO answer.
You also need to add them to the path. The tools were probably installed here: C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\Common7\Tools
Environment variable should be: VS140COMNTOOLS
Docker
To build Docker image from source using Dockerfile
:
$ docker build -t rotki .