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.

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.

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

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 npm. If you don’t, use your linux distro’s package manager to get them.

Get sqlcipher version 4:

  • If you are running Archlinux you can install the package with pacman.

  • If you are running Ubuntu, at the time of writing of this article Ubuntu is still using sqlcipher v3 which is not supported by rotki. So you should build sqlcipher v4 by hand. We have a script for that which is also used by our CI. Check it out here. Install libssl-dev and tclsh by running sudo apt-get install libssl-dev tclsh if not already installed.

  • If you are running openSUSE Tumbleweed, you can install sqlcipher v4 as follows:

    sudo zypper install sqlcipher sqlcipher-devel
    

rotki uses npm v7. To check if you have version 7 of npm you can run:

npm --version

If you are on an older version of npm, you can install it by:

npm install -g npm@7

Install electron and any other npm dependencies by:

cd frontend
npm ci

Create a new virtual environment with python 3.7 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.7

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 .

Before starting the application you need to build the common package. To do this you can go to frontend and run npm run build -w @rotki/common.

After that you can start the application from the frontend directory and typing npm run electron:serve -w rotki.

OSX

The tl;dr version is: - Install sqlcipher - Use a virtual env with Python 3.7.x - Confirm pip``(pip3) install correctly and up to date - Get your node under control with ``nvm. It has been tested with v14.16.0

The following recipe has been tested using Anaconda. VirtualEnv works as well, refer to the documentations of those projects to install and use them.

Install Homebrew first if not installed yet. rotki uses an encrypted database called SQLCipher. Before we can proceed, we need to install it. Homebrew makes it simple:

$ brew update
$ cd "$(brew --repo homebrew/core)"
$ git checkout 31f4d9cef46b1c39cdbe2f72ab682b5d0b02cf67 Formula/sqlcipher.rb #This formula installs 4.4.3 of sqlcipher
$ brew install sqlcipher

Also these are some dependencies that may or may not be properly installed in your system so make sure you have them.

$ brew install gmp

If you wish to use Conda, use the following commands:

$ brew tap homebrew/cask
$ brew install --cask homebrew/cask/anaconda
$ echo "export PATH=$PATH:/usr/local/anaconda3/bin" >> ~/.bash_profile
$ echo ". /usr/local/anaconda3/etc/profile.d/conda.sh" >> ~/.bash_profile
$ source ~/.bash_profile
$ conda create python=3.7 --name rotki
$ conda activate rotki

If you wish 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.7/bin/python3
export VIRTUALENVWRAPPER_VIRTUALENV=/Library/Frameworks/Python.framework/Versions/3.7/bin/virtualenv
source /Library/Frameworks/Python.framework/Versions/3.7/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:

$ sudo 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

Note

Make sure that pysqlcipher3 is properly installed. If $ pip3 freeze | grep pysqlcipher3 returns nothing for you then it was not installed. Try to manually install only that dependency with the verbose option to see where it fails. $ pip3 install pysqlcipher3 -v. If it fails at the stage of finding the library for -lsqlcipher then brew install sqlciper did not place the installed lib directory to the LIBRARY_PATH and you will have to do it manually. For example if sqlcipher was installed at /usr/local/Cellar/sqlcipher/4.4.0/ then use pip3 install this way:

$ LIBRARY_PATH=/usr/local/Cellar/sqlcipher/4.4.0/lib pip3 install pysqlcipher3.

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 npm v7. To check if you have version 7 of npm you can run:

npm --version

If you are on an older version of npm, you can install it by:

npm install -g npm@7

Almost there, we can now install all the Node.js dependencies of the frontend app. Using a recent Node.js version such as 14.16.0, it should be smooth. Also since npm uses gyp and that requires python 2.7 make sure to set it up appropriately before invoking npm:

$ cd frontend
$ npm ci
$ npm run build -w @rotki/common

You can now start rotki, still from the frontend directory:

$ npm run electron:serve

Windows

This is a guide on how to set up a rotki development environment in Windows from source.

Dependencies

Node & npm

Install node (includes npm).

Python
  1. Get python 3.7 (3.7 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 Varaiables” 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. Check the troubleshooting guide’s relevant section Microsoft Visual C++ 14.0 is required.

Git

Get latest git.

OpenSSL, Sqlcipher and pysqlcipher3

In order to build rotki on Windows, you will need to have installed and built pysqlcipher3 (instructions on this further down) which needs sqlcipher which needs OpenSSL.

  1. The guide requires you to get OpenSSL. You can do that from here.

    Note

    1. Because of some pysqlcipher3 dependencies, and because it most closely matches the version used in the sqlcipher build guide, you should get OpenSSL 1.0.2 and not 1.1.1 (the naming of libs and dlls has changed between versions and the building of some dependencies will fail).

    2. Get the version of OpenSSL that matches the architecture of your Windows and python installs (i.e. 32- or 64-bit)

    3. When prompted for an install directory for OpenSSL, choose one that does not have spaces in it (i.e. avoid Program Files) as installing it in a directory with spaces will cause you numerous headaches when trying to edit the Makefile mentioned in the sqlcipher build instructions.

    4. Verify that the <OpenSSL Install Dir>\bin directory is on your path after installation, pysqlcipher3 will not build/install correctly if it is missing

  2. As no pre-compiled Windows binaries and dlls are readily available for sqlcipher, you will need to build it from source. Here is a good guide on how to compile SQLCipher for Windows.

    Note

    1. Follow the instructions in the sqlcipher build guide regarding changes to Makefile.msc very closely, ensuring that variables that point to the directory where you have actually installed OpenSSL.

  3. Once you have completed up to and including Step 6 in the sqlcipher build guide (you can ignore Step 7), you will have compiled sqlcipher and built the necessary headers and libraries that pysqlcipher3 depends on. In the directory you should now see sqlcipher.dll, copy and paste this file to your <Windows>\System32 directory. These files will be used later; you can now move on to setting up your rotki dev environment.

Set up rotki dev environment

Docker

To build Docker image from source using Dockerfile:

$ docker build -t rotki .

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

At this point, it’s likely that pysqlcipher3 has not been built and installed correctly, and you will need to install it manually. If pysqlcipher3 installed successfully, you can skip Steps 7 - 9 and move on to the next section.

Since the electron application is located in a different directory you also need to do (NOTE: execute this only after pysqlcipher3 has successfully installed):

pip install -e .
  1. Go back to your development directory and download / clone (if you want to use git but don’t want to clone the whole project, check out degit) the source for pysqlcipher3.

  2. With your code editor of choice, edit the setup.py file in \pysqlcipher3\, make the following changes and save the file:

    Lines 165 - 169 Before
            ext_modules=[Extension(
            name=PACKAGE_NAME + EXTENSION_MODULE_NAME,
            sources=sources,
            define_macros=define_macros)
        ],
    Lines 165 ... AFTER
            ext_modules=[Extension(
            name=PACKAGE_NAME + EXTENSION_MODULE_NAME,
            sources=sources,
            library_dirs=[r'<DIRECTORY WHERE YOU BUILT SQLCIPHER TO (i.e. where the compiled sqlcipher.exe and sqlcipher.dll are)>'],
            include_dirs=[r'<THE PARENT DIRECTORY OF THE ABOVE DIRECTORY>'],
            define_macros=define_macros)
        ],
    
  3. Going back to the open terminal that you have, and ensuring that you are still in the rotki virtualenv that you created, navigate to the directory where you have downloaded the pysqlcipher3 source.

In the terminal execute the two following commands in succession:

python setup.py build
python setup.py install

If all went well, pysqlcipher3 should have successfuly built and installed. If it didn’t, try going back and ensuring that you have properly built sqlcipher and pointed to the right directories in the setup.py file, or consult the troubleshooting section.

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
    npm ci
    
  2. Next you should build the @rotki/common library:

    npm run build -w @rotki/common
    
  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:

    npm run electron:serve -w rotki
    

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.

3. Alternatively, you can also choose to build the application. In order to do so, navigate to your rotki development directory and execute the package.bat file. NOTE: You will need to edit the directories in the batch file to point to where you built pysqlcipher3 and your rotki development directory (see here).

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

Alternative dependencies with sqlciper amalgamation

This is a not so well tested way but some work has been done by cryptomental in this issue for it. With the amalgamation you can obtain all sqlcipher dependencies precompiled and amalgamated in one big blog. But … it’s tricky, hense not so well tested.

Read the issue for a lot of details and also the appveyor.yml for what needs to be done to build sqlcipher and keep the following in mind:

  1. Replace robocopy with copy -r and make sure to copy into python system include and not the venv one.

  2. If while building the amalgamation you get: "Fatal error: OpenSSL could not be detected!" try this SO answer. and make sure to add OPENSSL_CONF to the environment variables pointing to the location of openssl.conf.

  3. In addition copy the amalgamation dir’s ssl include folder to the python include folder:

    $ cp -r sqlcipher-amalgamation-3020001/openssl-include/openssl/ /c/Users/lefteris/AppData/Local/Programs/Python/Python37-32/include/openssl
    
  4. Copy the amalgamation dir’s ssl libraries to the python lib folder:

    $ cp sqlcipher-amalgamation-3020001/OpenSSL-Win32/* /c/Users/lefteris/AppData/Local/Programs/Python/Python37-32/libs/
    

    Note it has to be the OpenSSL-Win32 part.