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

  1. 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.

  2. 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 the C:\Users\<username>\AppData\Local\Programs\ directory.

  3. 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.

  4. 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).

  5. Make sure you have the latest version of pip installed by executing:

    pip install --upgrade pip

  6. 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.

  7. 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.

  1. Fork the relevant rotki branch into your own account in github.

  2. 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).

  3. 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).

  1. 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

  2. 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>

  1. 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 .

  1. 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

  1. 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

  2. If you get any errors you might need to build the @rotki/common library:

    pnpm run --filter @rotki/common build

  3. 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.

  1. 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 .