.. toctree:: :maxdepth: 2
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 :ref:`next section <packaged_binaries>`.
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.
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.
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.
brew install --cask rotki
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.
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.
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.
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).
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.
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, SLEEP_SECS,
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.
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
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.
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: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 :ref:`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.
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.
Make sure you have node.js and npm. If you don't, use your linux distro's package manager to get them.
rotki uses npm v8. To check if you have version 8 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@8
Install electron and any other npm dependencies by:
cd frontend npm ci
Create a new virtual environment with python 3.9 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.9
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 by typing npm 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 npm 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.
To package the application for your platform you need to run the packaging script. To do so you need to make sur
that packaging and ``requests are installed in your virtual environment
pip3 install packaging requests ./package.py --build full
The tl;dr version is:
- Use a virtual env with Python 3.9.x
- Confirm pip``(pip3) install correctly and up to date
- Get your node under control with ``nvm. It has been tested with v16
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.
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.9 --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.9/bin/python3 export VIRTUALENVWRAPPER_VIRTUALENV=/Library/Frameworks/Python.framework/Versions/3.9/bin/virtualenv source /Library/Frameworks/Python.framework/Versions/3.9/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 npm v8. To check if you have version 8 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@8
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 dev
To package the application for your platform you need to run the packaging script. To do so you need to make sur
that packaging and ``requests are installed in your virtual environment
pip3 install packaging requests ./package.py --build full
This is a guide on how to set up a rotki development environment in Windows from source.
Install node (includes npm).
Get python 3.9 (3.9 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 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 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
pythonthen 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 -Vinto 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 :ref:`microsoft_visual_studio_build_tools_required`.
Get latest git.
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 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>
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.
In your terminal, navigate to your rotki development directory and enter the following commands to install electron and its dependencies:
cd frontend npm ci
Next you should build the
@rotki/commonlibrary:npm run build -w @rotki/common
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.
Alternatively, you can also choose to build the application. In order to do so, navigate to your rotki development directory and execute the
package.pyfile.:pip3 install packaging requests python .\package.py --build full
If you get anyapi-ms-win-crt-runtime-l1-1-0.dll is missing error when running python follow this guide to resolve it.
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
To build Docker image from source using Dockerfile:
$ docker build -t rotki .