From 2cc0fb214b393d10a227f508a38c1b64e3cd8c81 Mon Sep 17 00:00:00 2001 From: Konstantinos Paparas Date: Fri, 10 Apr 2026 14:39:03 +0200 Subject: [PATCH 1/3] docs: fix broken anchors in PnL and tax-accounting pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Several links pointed at anchors that don't exist on the target pages after the usage-guides restructure: - history/pnl.md: #adding-manual-trades → #add-edit-events - history/pnl.md: settings/general#manage-historical-price-oracle-cache → settings/blockchain#oracle-cache - Multiple settings/accounting#accounting-settings (no such anchor on the page) dropped to the plain page link - tax-accounting/guide.md: fix double-dash #add--edit-events slug --- usage-guides/history/pnl.md | 6 +++--- .../tax-accounting/accounting-rules.md | 2 +- usage-guides/tax-accounting/guide.md | 18 +++++++++--------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/usage-guides/history/pnl.md b/usage-guides/history/pnl.md index ddbc168..522114f 100644 --- a/usage-guides/history/pnl.md +++ b/usage-guides/history/pnl.md @@ -131,7 +131,7 @@ It's possible that rotki is not able to find an acquisition event for a sale. In This can happen for many reasons. The asset may have been acquired in a non-supported exchange/protocol, some event not detected etc. -The way to fix it is to add either a [manual trade](/usage-guides/history/events#adding-manual-trades) to tell rotki how you acquired that asset or an acquisition history event. +The way to fix it is to [add a history event](/usage-guides/history/events#add-edit-events) (such as a Swap or Receive event) to tell rotki how you acquired that asset. ### Event counted as taxable / count as spend where they shouldn't @@ -154,12 +154,12 @@ Simply change the language on Google doc to United States. This can be done in F ![Missing prices asset](/images/sc_pnl_missing_prices.png) -It's possible that rotki is not able to find the price of assets. You have to input the price manually, otherwise the event will be skipped from pnl reports. For example if you are creating a GBP profit/loss report and the asset is GNO then make sure to create the GNO -> GBP historical price cache. You can add the prices on the spot, or open [manage historical price cache](/usage-guides/settings/general#manage-historical-price-oracle-cache). +It's possible that rotki is not able to find the price of assets. You have to input the price manually, otherwise the event will be skipped from pnl reports. For example if you are creating a GBP profit/loss report and the asset is GNO then make sure to create the GNO -> GBP historical price cache. You can add the prices on the spot, or open the [oracle cache](/usage-guides/settings/blockchain#oracle-cache) from the settings. ### The result of the generated PnL report is not what you expected. The results of the generated PnL report can vary depending on the -[accounting settings](/usage-guides/settings/accounting#accounting-settings). Check if any settings align with unusual treatments for your events, so you can adjust the settings to resolve the issue yourself. +[accounting settings](/usage-guides/settings/accounting). Check if any settings align with unusual treatments for your events, so you can adjust the settings to resolve the issue yourself. If you have any question or are confused about the settings, feel free to send us a message on [Discord](https://discord.rotki.com). diff --git a/usage-guides/tax-accounting/accounting-rules.md b/usage-guides/tax-accounting/accounting-rules.md index 638082c..5559047 100644 --- a/usage-guides/tax-accounting/accounting-rules.md +++ b/usage-guides/tax-accounting/accounting-rules.md @@ -4,7 +4,7 @@ description: Detailed explanation of every accounting setting in rotki including # Accounting Rule Options Explained -This page explains every accounting setting in rotki in detail. These settings control how your transactions are processed when generating a [Profit/Loss Report](/usage-guides/history/pnl). You can configure them under **Settings → Accounting Settings** ([screenshot guide](/usage-guides/settings/accounting#accounting-settings)). +This page explains every accounting setting in rotki in detail. These settings control how your transactions are processed when generating a [Profit/Loss Report](/usage-guides/history/pnl). You can configure them under **Settings → Accounting Settings** ([screenshot guide](/usage-guides/settings/accounting)). > [!IMPORTANT] > rotki's default settings are based on German tax rules. Check with your tax advisor about what's required in your country and adjust accordingly. diff --git a/usage-guides/tax-accounting/guide.md b/usage-guides/tax-accounting/guide.md index 9454e14..75dab3c 100644 --- a/usage-guides/tax-accounting/guide.md +++ b/usage-guides/tax-accounting/guide.md @@ -30,7 +30,7 @@ Before you can generate a tax report, rotki needs to know about your transaction ### 2. Configure your accounting settings -Go to **Settings → Accounting Settings** ([detailed reference](/usage-guides/settings/accounting#accounting-settings)) and configure: +Go to **Settings → Accounting Settings** ([detailed reference](/usage-guides/settings/accounting)) and configure: - **Cost basis method**: FIFO, LIFO, HIFO, or ACB — check which method your tax jurisdiction requires. See [accounting rule options explained](/usage-guides/tax-accounting/accounting-rules) for details. - **Crypto to crypto trades**: Whether swapping one crypto for another is a taxable event (it is in most jurisdictions). @@ -41,7 +41,7 @@ Go to **Settings → Accounting Settings** ([detailed reference](/usage-guides/s Go to **History Events** in the left sidebar. This is where all your transactions live. rotki automatically decodes most on-chain transactions, but you should review them for accuracy: -- **Check for missing events**: If you moved assets through unsupported protocols or peer-to-peer, you may need to [add events manually](/usage-guides/history/events#add--edit-events). +- **Check for missing events**: If you moved assets through unsupported protocols or peer-to-peer, you may need to [add events manually](/usage-guides/history/events#add-edit-events). - **Fix incorrectly categorized events**: rotki may not always correctly identify what a transaction represents. See the [event types and subtypes reference](/usage-guides/tax-accounting/event-types) to understand each category, and the [common customization guide](/usage-guides/history/events#common-customization) for how to re-categorize events. - **Check for missing accounting rules**: Events with a warning icon won't be processed correctly. Either edit the event or add a [missing accounting rule](/usage-guides/history/events#missing-accounting-rule). - **Match asset movements**: If you have exchange deposits/withdrawals that aren't linked to on-chain transactions, use the [asset movement matching](/usage-guides/history/events#unmatched-asset-movements) feature. @@ -70,13 +70,13 @@ The report shows: ## Common issues and how to fix them -| Problem | Likely cause | Solution | -| --------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| "No documented acquisition found" | rotki doesn't know when/where you originally bought an asset | [Add a manual trade](/usage-guides/history/events#add--edit-events) or acquisition event | -| Event counted as taxable when it shouldn't be | Wrong event type/subtype | [Edit the event](/usage-guides/history/events#common-customization) to the correct type | -| Missing price for an asset | Oracle doesn't have data for that asset/timestamp | [Add missing price manually](/usage-guides/data-management/prices) | -| PnL numbers seem wrong | Accounting settings may not match your jurisdiction | Review [accounting settings](/usage-guides/settings/accounting#accounting-settings) and [accounting rule options](/usage-guides/tax-accounting/accounting-rules) | -| Report generation gets stuck | Often caused by exchange API rate limits | Check [troubleshooting](/usage-guides/history/pnl#pnl-report-generation-gets-stuck) | +| Problem | Likely cause | Solution | +| --------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | +| "No documented acquisition found" | rotki doesn't know when/where you originally bought an asset | [Add a manual trade](/usage-guides/history/events#add-edit-events) or acquisition event | +| Event counted as taxable when it shouldn't be | Wrong event type/subtype | [Edit the event](/usage-guides/history/events#common-customization) to the correct type | +| Missing price for an asset | Oracle doesn't have data for that asset/timestamp | [Add missing price manually](/usage-guides/data-management/prices) | +| PnL numbers seem wrong | Accounting settings may not match your jurisdiction | Review [accounting settings](/usage-guides/settings/accounting) and [accounting rule options](/usage-guides/tax-accounting/accounting-rules) | +| Report generation gets stuck | Often caused by exchange API rate limits | Check [troubleshooting](/usage-guides/history/pnl#pnl-report-generation-gets-stuck) | ## What rotki currently does NOT support From 2fb4d828627585e2a59365974047d3e7ae829371 Mon Sep 17 00:00:00 2001 From: Konstantinos Paparas Date: Fri, 10 Apr 2026 14:39:58 +0200 Subject: [PATCH 2/3] docs: restructure installation into clearer paths MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Split the old packaged-binaries.md page into three focused pages so the simple download path isn't buried under Docker self-hosting and binary verification content: - download.md — Linux/macOS/Windows install (quick start for users) - docker.md — Docker image, Compose, Traefik+auth, Watchtower, migration from desktop (~350 lines extracted) - verify.md — SHA512 checksums and GitHub artifact attestations Rewrite the install index.md as a 4-card decision page (Download / Docker / Verify / Build from source) plus a minimum system requirements table. Collapse the three near-identical "Backend setup for Linux/macOS/ Windows" sections in build-from-source.md into a single section with OS-specific tabs. Drop the stale VS140COMNTOOLS / anyapi-ms-win-crt troubleshooting for dated Windows issues. Rename the sidebar group "System Requirements & Installation" → "Installation" and add entries for all four pages. Add an anchor-aware redirect for the old /packaged-binaries path so external links into Docker/Verify sections still resolve correctly. Update two internal docs cross-references that linked to the old path. --- .vitepress/config.mts | 26 +- contribution-guides/index.md | 2 +- .../build-from-source.md | 188 +++---- requirement-and-installation/docker.md | 293 +++++++++++ requirement-and-installation/download.md | 74 +++ requirement-and-installation/index.md | 25 +- .../packaged-binaries.md | 497 ------------------ requirement-and-installation/verify.md | 96 ++++ usage-guides/advanced/mobile.md | 2 +- 9 files changed, 577 insertions(+), 626 deletions(-) create mode 100644 requirement-and-installation/docker.md create mode 100644 requirement-and-installation/download.md delete mode 100644 requirement-and-installation/packaged-binaries.md create mode 100644 requirement-and-installation/verify.md diff --git a/.vitepress/config.mts b/.vitepress/config.mts index 67c50f2..4066067 100644 --- a/.vitepress/config.mts +++ b/.vitepress/config.mts @@ -32,6 +32,22 @@ const redirects: Record = { 'usage-guides/accessing-db-manually': '/usage-guides/advanced/database-access', 'usage-guides/using-rotki-from-mobile': '/usage-guides/advanced/mobile', // Anchor-aware redirects (split files) + 'requirement-and-installation/packaged-binaries': { + default: '/requirement-and-installation/download', + anchors: { + '#verifying-integrity': '/requirement-and-installation/verify', + '#github-artifact-attestations': '/requirement-and-installation/verify#github-artifact-attestations', + '#docker': '/requirement-and-installation/docker', + '#configuring-the-backend-in-docker': '/requirement-and-installation/docker#configuring-the-backend', + '#setting-timezone-in-docker': '/requirement-and-installation/docker#setting-the-timezone', + '#updating-to-a-newer-version': '/requirement-and-installation/docker#updating-to-a-newer-version', + '#docker-compose': '/requirement-and-installation/docker#docker-compose', + '#using-docker-over-a-public-network': '/requirement-and-installation/docker#public-network-with-traefik-basic-auth', + '#using-watchtower-for-continuous-deployment': '/requirement-and-installation/docker#watchtower-for-auto-updates', + '#using-docker-on-a-private-network': '/requirement-and-installation/docker#private-network', + '#moving-the-accounts-from-the-desktop-application': '/requirement-and-installation/docker#moving-accounts-from-the-desktop-app', + }, + }, 'usage-guides/accounts-and-balances': { default: '/usage-guides/portfolio/accounts', anchors: { @@ -119,11 +135,13 @@ export default defineConfig({ link: '/', }, { - text: 'System Requirements & Installation', + text: 'Installation', items: [ - { text: 'Installation', link: '/requirement-and-installation/' }, - { text: 'Packaged Binaries', link: '/requirement-and-installation/packaged-binaries' }, - { text: 'Build From Source', link: '/requirement-and-installation/build-from-source' }, + { text: 'Overview', link: '/requirement-and-installation/' }, + { text: 'Download & Install', link: '/requirement-and-installation/download' }, + { text: 'Docker & Self-Hosting', link: '/requirement-and-installation/docker' }, + { text: 'Verify Your Download', link: '/requirement-and-installation/verify' }, + { text: 'Build from Source', link: '/requirement-and-installation/build-from-source' }, ], }, { diff --git a/contribution-guides/index.md b/contribution-guides/index.md index fbd55ea..f13f64c 100644 --- a/contribution-guides/index.md +++ b/contribution-guides/index.md @@ -20,7 +20,7 @@ Before reporting an issue, make sure to check the issue tracker for similar ones For running rotki in debug mode, you can do it either via a config file or the app UI. The choice will depend on how you run rotki. -- **Config file**: See the section [Set the backend's arguments](/usage-guides/advanced/backend-config#set-the-backend-s-arguments). This is possible in the **electron app** and the **docker version**. For docker, you can even use environment variables as explained [here](/requirement-and-installation/packaged-binaries#configuring-the-backend-in-docker). +- **Config file**: See the section [Set the backend's arguments](/usage-guides/advanced/backend-config#set-the-backend-s-arguments). This is possible in the **electron app** and the **docker version**. For docker, you can even use environment variables as explained [here](/requirement-and-installation/docker#configuring-the-backend). - **App UI**: Before logging in, click the cogwheel in the bottom right corner and select "Debug" (image below). Press the save button and proceed to log in as usual. This is only possible in the **electron app**. ![Run rotki in debug mode via app UI](/images/rotki_debug_mode_set.png) diff --git a/requirement-and-installation/build-from-source.md b/requirement-and-installation/build-from-source.md index 5fceb2e..4ba17c7 100644 --- a/requirement-and-installation/build-from-source.md +++ b/requirement-and-installation/build-from-source.md @@ -1,11 +1,13 @@ --- -description: Building rotki from source with prerequisites, backend setup, frontend setup, and Colibri service compilation. +description: Build rotki from source for development or to run unreleased code, with backend, frontend, and packaging instructions. --- # Build from Source +Building rotki from source is for contributors and for users who want to run unreleased code from git branches. If you just want to use rotki, the [packaged binaries](/requirement-and-installation/download) are easier. + > [!WARNING] -> Please note that you should not switch between running unreleased code from git branches and official releases of rotki on the same [data set](/usage-guides/advanced/data-directory), as unreleased code does not provide guarantees around forward-compatibility of data schemas etc. +> Don't switch between unreleased git builds and official releases on the same [data directory](/usage-guides/advanced/data-directory). Unreleased code has no forward-compatibility guarantees for the database schema. ## Prerequisites @@ -13,148 +15,123 @@ Before starting, ensure you have the following installed: - [Git](https://git-scm.com/downloads) - [Python 3.11.x](https://www.python.org/downloads/) -- [uv](https://github.com/astral-sh/uv) (Python package manager) -- [Node.js](https://nodejs.org/en/) (version `>=24 <25` — check `frontend/package.json` `engines` for the exact requirement) -- [pnpm](https://pnpm.io/) (version `>=10 <11` — managed via `corepack`, see [Installing pnpm](#installing-pnpm)) -- [Rust/Cargo](https://www.rust-lang.org/tools/install) (needed to build the Colibri service locally) +- [uv](https://github.com/astral-sh/uv) — Python package manager +- [Node.js](https://nodejs.org/en/) — check `frontend/package.json` `engines` for the exact supported range +- [pnpm](https://pnpm.io/) — managed via `corepack` (see [Installing pnpm](#installing-pnpm)) +- [Rust / Cargo](https://www.rust-lang.org/tools/install) — needed to build the Colibri service locally + +## Get the source -## Downloading source +Fork the rotki repository on GitHub, then clone your fork locally: -This guide assumes you want to use Git to clone the project into a development directory; if you prefer to download the source from GitHub as a zip, you can do that instead. +```sh +git clone https://github.com/your-user/rotki.git +cd rotki +``` -1. Fork the relevant rotki branch into your own GitHub account. -2. Open a terminal (Command Prompt / PowerShell prompt) 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 rotki/develop branch, you might clone into `c:\dev\rotki-develop`). +This guide assumes you checked out the `develop` branch, which is the default for contributors. -In your local rotki development directory, you should have all the files as they appear in the GitHub page for the rotki branch you chose to download/clone. +## Backend setup -## Backend setup for Linux +The backend setup is the same across Linux, macOS, and Windows — install `uv`, then run `uv sync` to create the development environment. OS-specific notes are below. -### Set Up Python Environment +### Install uv -Install uv, the modern Python package manager: +**Linux and macOS:** ```sh curl -LsSf https://astral.sh/uv/install.sh | sh ``` -Then set up the development environment: +**Windows (PowerShell):** ```sh -# Install all dependencies including dev and lint groups -uv sync --group dev --group lint +powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` -Follow the [Frontend setup](#frontend-setup) to complete the setup. - -## Backend setup for macOS +### Install dependencies -The tl;dr version is: +From the rotki repo root: -- Use a virtual environment with Python 3.11.x. -- Confirm `pip` (pip3) is installed correctly and up to date. +```sh +uv sync --group dev --group lint +``` -Install [Homebrew](https://brew.sh/) first if not installed yet. +This creates a `.venv` and installs the backend, dev, and lint dependency groups. -### Set Up Python Environment +### Verify the backend -Install uv, the modern Python package manager: +Start the backend once to confirm it runs: ```sh -curl -LsSf https://astral.sh/uv/install.sh | sh +uv run python -m rotkehlchen ``` -Then set up the development environment: +You should see: -```sh -# Install all dependencies including dev and lint groups -uv sync --group dev --group lint +``` +rotki REST API server is running at: 127.0.0.1:5042 ``` -Follow the [Frontend setup](#frontend-setup) to complete the setup. +Stop it with `Ctrl+C` — we'll run everything together once the frontend is set up. -## Backend setup for Windows +### OS-specific notes -### Dependencies +::: tabs -1. Install [Python 3.11](https://www.python.org/downloads/release/python-3117/) (64-bit version for 64-bit Windows). -2. Ensure Python is in the Path variable. If not: - - Go to Control Panel -> System -> Advanced system settings -> Advanced (tab) -> Environment Variables... - - Under "System Variables," open the "Path" variable and ensure both the root Python directory and the `Scripts` subdirectory are included. - - If not, add them by clicking "New" and then "Browse" and locating the correct directories. - - By default, the Windows MSI installer places Python in the `C:\Users\\AppData\Local\Programs\` directory. -3. Test Python installation by opening a command prompt and typing `python`. The Python CLI should run, showing the Python version you installed. Press `CTRL+Z`, then Enter to exit. - > **Note:** In newer versions of Windows, typing "python" may open the Windows Store. Fix this by opening "App execution aliases" (search for it via Windows Search) and toggling off the aliases for python.exe and python3.exe. -4. Install uv, the modern Python package manager. Open PowerShell as Administrator and run: - ```sh - powershell -c "irm https://astral.sh/uv/install.ps1 | iex" - ``` -5. Install [Microsoft Visual Studio build tools](https://visualstudio.microsoft.com/vs/) with the "Desktop development with C++" workload. +== macOS -### Set Up Python Environment +Install [Homebrew](https://brew.sh/) first if you don't have it. Homebrew is used as a bootstrap for Python 3.11 and other toolchain dependencies. + +== Windows + +1. Install [Python 3.11](https://www.python.org/downloads/release/python-3117/) (64-bit). +2. Make sure Python is on your `Path`. If not, add both the root Python directory and the `Scripts` subdirectory via **Control Panel → System → Advanced system settings → Environment Variables**. +3. Test with `python` in a Command Prompt. If Windows opens the Store instead, disable the `python.exe` and `python3.exe` aliases under **App execution aliases**. +4. Install the [Visual Studio Build Tools](https://visualstudio.microsoft.com/vs/) with the **Desktop development with C++** workload. +5. After `uv sync`, download [miniupnpc for Windows](https://github.com/mrx23dot/miniupnp/releases/download/miniupnpd_2_2_24/miniupnpc_64bit_py39-2.2.24.zip) and copy `miniupnpc.dll` into the venv's site-packages directory. Find the path with: -1. Open a terminal (Command Prompt / PowerShell prompt) in your root development directory. -2. Ensure you are in the directory where you downloaded/cloned the rotki source. -3. Install all dependencies: - ```sh - # Install all dependencies including dev and lint groups - uv sync --group dev --group lint - ``` -4. Download [miniupnpc for Windows](https://github.com/mrx23dot/miniupnp/releases/download/miniupnpd_2_2_24/miniupnpc_64bit_py39-2.2.24.zip) and copy `miniupnpc.dll` to your virtual environment's `Lib > site-packages` directory. Locate this directory using: ```sh uv run python -c "import site; print(site.getsitepackages()[0])" ``` -Then follow the [Frontend setup](#frontend-setup) to complete the setup. +== Linux -To ensure rotki backend works, try starting it: +No extra steps — `uv sync` handles everything. -```sh -uv run python -m rotkehlchen -``` - -This should greet you with the message: - -``` -rotki REST API server is running at: 127.0.0.1:5042 -``` +::: ## Frontend setup -Make sure you have Node.js installed (version `>=24 <25`). You can check https://nodejs.org/en/download/package-manager for more information. +The frontend lives under `frontend/` and uses pnpm. ### Installing pnpm -The project uses [corepack](https://nodejs.org/api/corepack.html) to manage the pnpm version. Enable it and corepack will automatically use the version specified in `frontend/package.json` under the `packageManager` key: +The repo uses [corepack](https://nodejs.org/api/corepack.html) to manage pnpm. Enable it and corepack will automatically use the version pinned in `frontend/package.json` under `packageManager`: ```sh corepack enable pnpm -``` - -To verify: - -```sh pnpm --version ``` -### Install Node.js Dependencies +### Install dependencies ```sh cd frontend pnpm install --frozen-lockfile ``` -### Running rotki +### Run rotki in development mode -Start the application from the `frontend` directory: +From the `frontend/` directory: ```sh pnpm run dev ``` -This starts the Electron app with the backend, Colibri service (if Cargo is available), and the frontend dev server. If `VITE_BACKEND_URL` is set in `frontend/app/.env.development.local`, the [development proxy](/contribution-guides/working-with-frontend#development-proxy) is also started automatically. +This starts the Electron app together with the backend, the Colibri service (if Cargo is available), and the frontend dev server. If `VITE_BACKEND_URL` is set in `frontend/app/.env.development.local`, the [development proxy](/contribution-guides/working-with-frontend#development-proxy) starts as well. -For browser-only development (no Electron): +For browser-only development (no Electron), use: ```sh pnpm run dev:web @@ -164,7 +141,7 @@ See [Working with the Frontend](/contribution-guides/working-with-frontend) for ## Packaging -To package the application for your platform, you need to install the packaging dependencies and run the packaging script: +To build a distributable package for your platform: ```sh # Install packaging dependencies @@ -176,7 +153,7 @@ uv run python ./package.py --build full ## Nix -You can use the [Nix](https://nixos.org/download) package manager to start rotki development. Create `flake.nix` in the root of the project and copy the following into it: +If you use [Nix](https://nixos.org/download), create a `flake.nix` at the repo root with the following: ```nix { @@ -207,15 +184,12 @@ You can use the [Nix](https://nixos.org/download) package manager to start rotki pkgs.git pkgs.lzma pnpmWithPython311 - python311 # interpreter uv will bind into the venv - pkgs.uv # blazing-fast venv + installer + python311 + pkgs.uv ]; shellHook = '' - # Installs deps and auto-creates .venv if missing uv sync - - # Install frontend dependencies cd frontend pnpm install cd .. @@ -225,22 +199,17 @@ You can use the [Nix](https://nixos.org/download) package manager to start rotki } ``` -Then execute the following command to let Nix build the entire environment where you can start rotki development: +Then enter the development environment with: ```sh nix develop -``` - -From this point onward, start backend/frontend: - -```sh cd frontend pnpm run dev:web ``` -## Docker +## Building a Docker image -To build Docker image from source using `Dockerfile`: +To build a Docker image from source using the repo's `Dockerfile`: ```sh docker build -t rotki . @@ -248,35 +217,14 @@ docker build -t rotki . ## 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](https://www.ghacks.net/2017/06/06/the-program-cant-start-because-api-ms-win-crt-runtime-l1-1-0-dll-is-missing/) to resolve it. - -### Microsoft Visual C++ 14.0 is required - -If you get: - -```sh -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](https://visualstudio.microsoft.com/downloads/) 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 Stack Overflow answer](https://stackoverflow.com/questions/29846087/microsoft-visual-c-14-0-is-required-unable-to-find-vcvarsall-bat/49986365#49986365). - -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` - ### Blank screen when running the dev server -If you get a blank screen on electron when starting the development server check the console for -any messages like the following: +If you get a blank screen on Electron when starting the dev server, check the console for a syntax-error message: ![Syntax Error](/images/troubleshooting_syntax_error.png) -If you see any syntax error message like the one above, go to `Help` and press `Clear Cache`. -After that go to the `View` menu and press `Force Reload`. +If you see one, go to `Help → Clear Cache`, then `View → Force Reload`. If the issue persists, follow the frontend [troubleshooting steps](/contribution-guides/vue-typescript#troubleshooting). -This should resolve your issue. +### Windows build tool errors -If the issue persists, -try following the frontend [troubleshooting steps](/contribution-guides/vue-typescript#troubleshooting). +If `uv sync` fails on Windows with errors like `Microsoft Visual C++ 14.0 is required`, the Visual Studio Build Tools aren't installed correctly. Make sure you selected the **Desktop development with C++** workload when installing — see the [prerequisites](#backend-setup) above. diff --git a/requirement-and-installation/docker.md b/requirement-and-installation/docker.md new file mode 100644 index 0000000..a94af10 --- /dev/null +++ b/requirement-and-installation/docker.md @@ -0,0 +1,293 @@ +--- +description: Run rotki in a Docker container, with configuration, Docker Compose templates, updating, and migrating data from the desktop app. +--- + +# Docker & Self-Hosting + +rotki provides official Docker images starting from v1.11.0. Images are published on [DockerHub](https://hub.docker.com/r/rotki/rotki) as `rotki/rotki`. + +> [!WARNING] +> rotki was not designed to run over a public network. Keep the container inside a trusted environment (for example, on your home LAN or behind a VPN) and do not expose it directly to the internet to avoid unauthorized access to your data. + +> [!NOTE] +> Versions up to v1.13.2 report a dev version inside the app due to an old build process issue. This is cosmetic and doesn't affect functionality. + +## Quick start + +Pull the latest image: + +```sh +docker pull rotki/rotki:latest +``` + +Start a container with persistent data and log volumes: + +```sh +docker run -d --name rotki \ + -p 8084:80 \ + -v $HOME/.rotki/data:/data \ + -v $HOME/.rotki/logs:/logs \ + rotki/rotki:latest +``` + +Open `http://localhost:8084` in your browser and you'll see the rotki login screen. If port `8084` is taken, pick any free port and change the left-hand side of `-p`. + +Your account data lives under `~/.rotki/data`; your logs are under `~/.rotki/logs`. Both survive container restarts and upgrades as long as you reuse the same volumes. + +> [!WARNING] +> On Linux, the mounted `data` and `logs` folders must be owned by `root` — that's the user the container runs as. If you change the owner, the container will hit permission errors and rotki will return 500 responses. + +## Configuring the backend + +You can tune the backend with either a config file or environment variables. If both are present, the config file takes precedence. + +### Config file + +Mount an extra volume for config: + +```sh +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 +``` + +Create `$HOME/.rotki/config/rotki_config.json`: + +```json +{ + "loglevel": "info", + "logfromothermodules": true, + "sleep-secs": 22, + "max_size_in_mb_all_logs": 550, + "max_logfiles_num": 3, + "sqlite_instructions": 0 +} +``` + +You can include only the options you want to override. Restart the container to apply changes. + +### Environment variables + +```sh +docker run -d --name rotki \ + -p 8084:80 \ + -v $HOME/.rotki/data:/data \ + -v $HOME/.rotki/logs:/logs \ + -e LOGLEVEL=debug \ + rotki/rotki:latest +``` + +Supported variables: `LOGLEVEL`, `LOGFROMOTHERMODULES`, `MAX_SIZE_IN_MB_ALL_LOGS`, `MAX_LOGFILES_NUM`, `SQLITE_INSTRUCTIONS`. Changing these requires recreating the container. + +## Setting the timezone + +Set `TZ` when starting the container: + +```sh +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 +``` + +See the [tz database list](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for valid values. + +## Updating to a newer version + +When a new rotki version is released: + +```sh +# 1. Stop and remove the old container (data lives in volumes, so this is safe) +docker stop rotki +docker rm rotki + +# 2. Pull the latest image +docker pull rotki/rotki:latest + +# 3. Start a new container — reuse the same volumes +docker run -d --name rotki \ + -p 8084:80 \ + -v $HOME/.rotki/data:/data \ + -v $HOME/.rotki/logs:/logs \ + rotki/rotki:latest +``` + +> [!IMPORTANT] +> Always reuse the same volumes. If you mount different ones, your existing accounts and data won't be visible to the new container. + +## Docker Compose + +For most users, a simple private-network Compose file is the easiest way to keep rotki running. + +### Private network + +**Using Docker-managed volumes:** + +```yaml +version: '3.7' +services: + rotki: + environment: + - TZ=America/Chicago + image: rotki/rotki:latest + ports: + - '8084:80' + networks: + - rotki-net + volumes: + - rotki-data:/data + - rotki-logs:/logs +volumes: + rotki-data: + rotki-logs: +networks: + rotki-net: +``` + +**Using host paths:** + +```yaml +version: '3.7' +services: + rotki: + environment: + - TZ=America/Chicago + image: rotki/rotki:latest + ports: + - '8084:80' + networks: + - rotki-net + volumes: + - $HOME/.rotki/data:/data + - $HOME/.rotki/logs:/logs +networks: + rotki-net: +``` + +### Public network with Traefik + basic auth + +> [!WARNING] +> Exposing rotki to the public internet is not recommended. If you do, protect it with at least basic authentication and TLS. + +This setup uses Traefik as a reverse proxy with basic auth and automatic Let's Encrypt TLS. Assuming you have a server at `rotki.example.com`: + +1. Create a bcrypt-hashed password for the basic auth user: + + ```sh + htpasswd -cB ~/.rotki/.htpasswd user + ``` + +2. Create `.env` next to `docker-compose.yml`: + + ```sh + AUTH_USER=username + FQDN=rotki.example.com + LETSENCRYPT_EMAIL=user@example.com + ``` + +3. Create `docker-compose.yml`: + + ```yaml + version: '3.11' + 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 + 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: + ``` + +4. Start it: + + ```sh + docker-compose up -d + ``` + +Visiting `http://rotki.example.com` will prompt for the basic auth user and password, then redirect to the rotki login page over HTTPS. This also makes rotki reachable from your mobile device. + +### Watchtower for auto-updates + +Add a Watchtower service to the compose file above for zero-downtime updates (`--rolling-restart`): + +```yaml +watchtower: + image: containrrr/watchtower + command: + - --label-enable + - --interval + - '60' + - --rolling-restart + volumes: + - /var/run/docker.sock:/var/run/docker.sock +``` + +Then add this label to the `rotki` service so Watchtower manages it: + +```yaml +labels: + - com.centurylinklabs.watchtower.enable=true +``` + +## Moving accounts from the desktop app + +If you've been running rotki as a desktop app and want to switch to Docker, you can copy your account files into the Docker data volume. + +Find the desktop app's data directory using the [rotki data directory guide](/usage-guides/advanced/data-directory#rotki-data-directory), then copy any specific account over: + +```sh +# Example: Linux, user "alice", data volume at ~/.rotki/data +sudo cp -R ~/.local/share/rotki/data/alice ~/.rotki/data/alice +``` + +The next time you start the Docker container, the `alice` account will appear on the login screen. + +## Troubleshooting + +If you hit issues, check the logs at `$HOME/.rotki/logs/rotki.log` (or your custom logs volume) and [open an issue on GitHub](https://github.com/rotki/rotki/issues/new/choose) with the relevant lines. diff --git a/requirement-and-installation/download.md b/requirement-and-installation/download.md new file mode 100644 index 0000000..a2b8a9b --- /dev/null +++ b/requirement-and-installation/download.md @@ -0,0 +1,74 @@ +--- +description: Download and install rotki on Linux, macOS, or Windows using the official pre-built binaries. +--- + +# Download & Install + +The easiest way to run rotki is to download a pre-built binary for your operating system from the [official releases page](https://github.com/rotki/rotki/releases/latest). + +Pick the package for your platform: + +- **Linux** — `rotki-linux_x86_64-*.AppImage` (or `.tar.xz`) +- **macOS** — `rotki-darwin-*.dmg` (Intel or Apple Silicon) +- **Windows** — `rotki-win32-*.exe` (installer) + +After installing, you can optionally [verify your download](/requirement-and-installation/verify) to confirm the binary is authentic. + +## Linux + +### AppImage + +Download the `linux-x64` AppImage from the [latest release](https://github.com/rotki/rotki/releases/latest) and make it executable: + +```sh +chmod +x rotki-linux_x86_64-vx.x.x.AppImage +``` + +Replace `vx.x.x` with the version you downloaded, then run the file to start rotki. + +### Tarball + +Alternatively, download the `.tar.xz` archive and unpack it in a directory of your choice. The extracted folder contains a `rotki` executable — run it from the terminal to start rotki. + +## macOS + +### Homebrew + +The simplest option on macOS is Homebrew: + +```sh +brew install --cask rotki +``` + +### Manual install + +Download the `darwin-x64` (Intel) or `darwin-arm64` (Apple Silicon) `.dmg` from the [latest release](https://github.com/rotki/rotki/releases/latest). Open the installer and drag the rotki icon into your **Applications** folder. You can then launch rotki from Launchpad or Finder. + +> [!NOTE] +> If macOS blocks the app the first time you open it, go to **System Settings → Privacy & Security** and allow rotki to run. See [this guide](https://ccm.net/faq/29619-mac-os-x-run-apps-downloaded-from-unknown-sources) for screenshots. + +## Windows + +Download the `win32-x64` installer from the [latest release](https://github.com/rotki/rotki/releases/latest) and run it. Windows Defender or your antivirus may prompt you — the binary is signed by **Rotki Solutions GmbH**, which you can confirm by right-clicking the installer and checking its digital signature. + +## First launch + +When rotki starts for the first time you'll see a sign-in/sign-up screen. From there you can create a local account and begin tracking your portfolio — see the [Quick Start Guide](/usage-guides/quick-start) for a step-by-step walkthrough. + +## Troubleshooting + +If rotki fails to start or crashes during use, please [open an issue on GitHub](https://github.com/rotki/rotki/issues/new/choose) and include the log files found at: + +| OS | Log directory | +| ------- | ------------------------------------------- | +| Linux | `~/.config/rotki/logs/` | +| macOS | `~/Library/Application Support/rotki/logs/` | +| Windows | `%APPDATA%\rotki\logs\` | + +On Windows, you can also run the executable from the Command Prompt to capture startup errors printed to the console. + +## See also + +- [Verify Your Download](/requirement-and-installation/verify) — confirm your binary is authentic +- [Docker & Self-Hosting](/requirement-and-installation/docker) — run rotki in a container +- [Build from Source](/requirement-and-installation/build-from-source) — for contributors and developers diff --git a/requirement-and-installation/index.md b/requirement-and-installation/index.md index caaf996..dda7c09 100644 --- a/requirement-and-installation/index.md +++ b/requirement-and-installation/index.md @@ -1,9 +1,28 @@ --- -description: Overview of rotki installation options with links to packaged binaries and building from source. +description: Install rotki from pre-built binaries, run it in Docker, or build from source. --- # Installation -The easiest way to start rotki is to download the packaged binary for your operating system. Linux, macOS, and Windows are supported. To see how to do this, go to the [next section](/requirement-and-installation/packaged-binaries). +rotki runs locally on your machine — no accounts or cloud services are required to get started. Pick the path that matches your use case: -If you have rotki installed and running well, you can go to the [usage guide](/usage-guides/) + + +## System requirements + +| Requirement | Minimum | +| ----------- | --------------------------------------------------------- | +| **Linux** | Any modern 64-bit distribution with glibc 2.28+ | +| **macOS** | Big Sur (11) or later, Intel or Apple Silicon | +| **Windows** | Windows 10 (64-bit) or later | +| **RAM** | 4 GB (8 GB recommended for large portfolios) | +| **Disk** | 2 GB free for the app, plus space for your local database | + +## What's next? + +Once rotki is installed, head to the [Quick Start Guide](/usage-guides/quick-start) for a step-by-step walkthrough from creating an account to generating your first PnL report. diff --git a/requirement-and-installation/packaged-binaries.md b/requirement-and-installation/packaged-binaries.md deleted file mode 100644 index db71442..0000000 --- a/requirement-and-installation/packaged-binaries.md +++ /dev/null @@ -1,497 +0,0 @@ ---- -description: Installing rotki from packaged binaries on Linux, macOS, and Windows, including Docker and DAppNode. ---- - -# 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](https://github.com/rotki/rotki/releases). - -The files containing the hash have the same name as their respective binaries followed by a `.sha512` extension. - -To verify a binary, download the `.sha512` file for it. Then, proceed with the verification: - -### On Linux: - -```sh -cd ~/Downloads -sha512sum -c rotki-linux_x86_64-vx.x.x.AppImage.sha512 -# rotki-linux_x86_64-vx.x.x.AppImage: OK -``` - -### On macOS: - -```sh -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 see an error similar to the following: - -```sh -rotki-linux_x86_64-vx.x.x.AppImage: FAILED -sha512sum: WARNING: 1 computed checksum did NOT match -``` - -### On Windows: - -First, open the Command Prompt and navigate to the `Downloads` directory where the rotki executable and SHA512 files were downloaded: - -```sh -cd Downloads -certutil -hashfile rotki-win32-vx.x.x.exe SHA512 -``` - -After running the command, you should see the command's output: - -```sh -SHA512 hash of rotki-win32-v1.6.2.exe: -a3e0d79724460f642245774ba1af4c7116dfde56503d134c688f406afff5339f70a84a0bdb2556bc0785931b11e2447e3ffcd116cdec9e8a50382ec0165788b4 -CertUtil: -hashfile command completed successfully. -``` - -To verify that the generated hash matches, open the `rotki-win32-vx.x.x.exe.sha512` file with Notepad or any other text editor and ensure that the hash there matches the one generated by the certutil command. - -> **Note:** Depending on your OS, you can check the details by right-clicking on the app: -> -> - **Windows:** The signature will display "Rotki Solutions GmbH". -> - **macOS:** In the "Get Info" window, the copyright should read "Rotki Solutions GmbH". - -## GitHub Artifact Attestations - -Rotki uses **GitHub Artifact Attestations** to help you verify that your downloaded binary is authentic and hasn't been tampered with. This feature creates a cryptographic link between the source code and the final executable, showing you exactly which code version, build environment, and workflow created your binary. - -When you verify an attestation, you're confirming that the software was genuinely built from the expected repository and commit, providing protection against supply chain attacks. This gives you confidence that what you're downloading is exactly what the developers intended to release. - -You can verify any rotki binary using the GitHub CLI to check its attestation and see the workflow that created it. For detailed instructions, see the [GitHub docs](https://cli.github.com/manual/gh_attestation_verify). - -Example: - -```sh -$ gh attestation verify ~/Downloads/rotki134.dmg --repo rotki/rotki -Loaded digest sha256:12bb7aa1cf8d5b568f925e7c772b946a29efaf66ae030026a1f113da528c8e39 for file:///Users/yabirgb/Downloads/rotki134.dmg -Loaded 1 attestation from GitHub API -✓ Verification succeeded! - -sha256:12bb7aa1cf8d5b568f925e7c772b946a29efaf66ae030026a1f113da528c8e39 was attested by: -REPO PREDICATE_TYPE WORKFLOW -rotki/rotki https://slsa.dev/provenance/v1 .github/workflows/rotki_release.yaml@refs/tags/v1.34.0 -``` - -> [!WARNING] -> -> GitHub artifact attestations will fail for Windows binaries (`rotki-win32_x64-v1.x.x.exe`) that have been published after August 2025. -> -> To have a verified Publisher on Windows, binaries have to be re-signed locally using a hardware key (Yubikey) using an OV Certificate. -> This causes the binary hash to change, which in turn causes the GitHub artifact attestation to fail. -> -> For windows binaries verify that the binary is signed by **Rotki Solutions GmbH**. - -## Linux - -Go to the [releases](https://github.com/rotki/rotki/releases) page and download the `linux-x64` AppImage from the [latest release](https://github.com/rotki/rotki/releases/latest), or the `.tar.xz` file, whichever you prefer. - -If you downloaded the AppImage, give it executable permission: - -```sh -chmod +x rotki-linux_x86_64-vx.x.x.AppImage -``` - -Replace `vx.x.x` with the proper version, then run it. - -If you downloaded the tar file, 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 encounter any issues when starting the application or during its usage, please open an issue on GitHub and include all logs found in `~/.config/rotki/logs`. - -## macOS - -### Homebrew - -```sh -brew install --cask rotki -``` - -### Manual Installation - -Go to the [releases](https://github.com/rotki/rotki/releases) page and download the `darwin-x64` dmg package from the [latest release](https://github.com/rotki/rotki/releases/latest). - -> **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 limitation is due to Apple's policy. - -Click on the dmg installer and when prompted, drag the rotki logo to your Applications folder. This will install the application. Once finished, you can select rotki from your Applications folder and launch it. - -If your macOS version does not allow you to open the application, you will need to go to your OS settings and insert an exception for rotki to allow it to run. [Here](https://ccm.net/faq/29619-mac-os-x-run-apps-downloaded-from-unknown-sources) is a guide. - -### Troubleshooting - -If you encounter any issues when starting the application or during its usage, please open an issue on GitHub and include all logs found in `~/Library/Application Support/rotki/logs`. - -## Windows - -Go to the [releases](https://github.com/rotki/rotki/releases) page and download the `win32-x64` package from the [latest release](https://github.com/rotki/rotki/releases/latest). - -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 encounter "The python backend crashed" or any other error, please run the executable via the Command Prompt and provide us with the output visible in the prompt to help us debug your issue. - -You should also include all logs found in `:\Users\\AppData\Roaming\rotki\logs\` (`%APPDATA%\rotki\logs`). - -## Docker - -Since v1.11.0, rotki provides official Docker images of nightly versions and releases. - -> **Note:** Versions up to v1.13.2 report a dev version instead of the actual release due to an issue during the build process. - -You can find all the available Docker images on [DockerHub](https://hub.docker.com/r/rotki/rotki). - -> [!WARNING] -> It is advisable to run the Docker image in a secure environment. For example, running the Docker image on the host machine and accessing it only via NAT. Do not expose the Docker image directly to public or local networks to avoid security issues and unauthorized access to your data. - -To get the latest version of rotki, pull the `latest` tag: - -```sh -docker pull rotki/rotki:latest -``` - -To start a container based on the latest rotki image, run the following: - -```sh -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 folders changes to another user, they will become inaccessible by the container, resulting in 500 errors when accessing rotki in the container. To fix this issue, change the directory owner back to `root`. - -This will start a new container that stores the data and logs in 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` is busy on your machine, choose any other available port. - -At this point, the rotki Docker container should be running, and you should be able to access the rotki frontend by opening your browser and navigating to `http://localhost:8084`. You should see the rotki login screen. - -### Configuring the Backend in Docker - -It is possible to change the configuration of the backend in the Docker container using two different approaches. - -The first approach includes mounting a config volume: - -```sh -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 -``` - -Create a `rotki_config.json` file and place it inside the `$HOME/.rotki/config` directory. - -Example: - -```json -{ - "loglevel": "info", - "logfromothermodules": true, - "sleep-secs": 22, - "max_size_in_mb_all_logs": 550, - "max_logfiles_num": 3, - "sqlite_instructions": 0 -} -``` - -The above list contains all the supported configuration options, but you can also specify only the ones you want to change. This approach allows you to modify the config and restart the container to apply them. - -The second approach uses environment variables during container creation: - -```sh -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`, `LOGFROMOTHERMODULES`, `MAX_SIZE_IN_MB_ALL_LOGS`, `MAX_LOGFILES_NUM`, and `SQLITE_INSTRUCTIONS`. Changing these variables requires recreating the container with the new parameters. - -> **Warning:** When using both a config file and environment variables, the config file will take precedence. - -### Setting Timezone in Docker - -To set the timezone in the Docker environment, use the `-e TZ=Timezone` option when starting the container: - -```sh -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 released, follow these steps to upgrade to the newest version: - -1. Stop the rotki container from running: - - ```sh - docker stop rotki - ``` - -2. Remove the old container: - ```sh - docker rm rotki - ``` - -Since your data is stored in volumes on the host machine, deleting the container will not affect your data. - -3. Pull the latest tag from Docker Hub: - - ```sh - docker pull rotki/rotki:latest - ``` - -4. Create a new container: - ```sh - docker run -d --name rotki \ - -p 8084:80 \ - -v $HOME/.rotki/data:/data \ - -v $HOME/.rotki/logs:/logs \ - rotki/rotki:latest - ``` - -Ensure that the volumes from the previous container are used again. If you don’t use the same volumes, 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](#docker) to avoid directly exposing your rotki instance over a 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 who visits your public domain will need to authenticate with the basic auth user and password before accessing rotki's user interface. - -Additionally, Traefik will be set up to automatically request and set up an SSL certificate to ensure that your connection to your rotki instance is properly encrypted using TLS. - -Assuming you have a server provisioned and a domain `rotki.example.com` already set to the server's IP address: - -1. Create a basic auth user with a password. Use the Apache utilities to create a secure password using `bcrypt` for your user: - - ```sh - htpasswd -cB ~/.rotki/.htpasswd user - ``` - -2. 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 email where you will receive notifications about the status of your domain: - - ```sh - AUTH_USER=username - FQDN=rotki.example.com - LETSENCRYPT_EMAIL=user@example.com - ``` - -3. Create the `docker-compose.yml`: - - ```yaml - version: '3.11' - - 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: - ``` - -4. Run: - ```sh - docker-compose up -d - ``` - -With this setup, 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 enter the `AUTH_USER` and the password you created with `htpasswd`. - -After passing the basic 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 Watchtower for Continuous Deployment - -Add a watchtower service to the `docker-compose.yml`. Using `--rolling-restart` ensures zero downtime when pulling and switching to the latest version: - -```yaml -version: '3.11' - -services: - watchtower: - image: containrrr/watchtower - command: - - --label-enable - - --interval - - '60' - - --rolling-restart - volumes: - - /var/run/docker.sock:/var/run/docker.sock - 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 - - com.centurylinklabs.watchtower.enable=true - -networks: - rotki-net: -``` - -### Using Docker on a Private Network - -**Using Docker Defined Volume:** - -```yaml -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 whichever path to your local data) Defined Directed Volume:** - -```yaml -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 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](/usage-guides/advanced/data-directory#rotki-data-directory). - -To move your existing accounts from the application, copy the contents of the application data directory to the data volume mount point. - -Assuming you used the directory from the example, to move a specific account on Linux, run: - -```sh -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 encounter any issues when starting the application or during its usage, please open an issue on GitHub and include all logs found in `$HOME/.rotki/logs/rotki.log` or the custom volume you used during the container diff --git a/requirement-and-installation/verify.md b/requirement-and-installation/verify.md new file mode 100644 index 0000000..fdc0438 --- /dev/null +++ b/requirement-and-installation/verify.md @@ -0,0 +1,96 @@ +--- +description: Verify the integrity and authenticity of rotki binaries using SHA512 checksums and GitHub Artifact Attestations. +--- + +# Verify Your Download + +Verifying your download confirms that the binary you downloaded is the exact file that was built and published by the rotki team. This is optional, but recommended if you want to protect yourself from supply chain attacks or tampered mirrors. + +There are two independent ways to verify a rotki binary: + +1. **SHA512 checksum** — quick integrity check against a published hash +2. **GitHub Artifact Attestations** — cryptographic proof that the binary was built from the official rotki source on GitHub + +You only need to do one of these to trust a binary; doing both gives you the strongest guarantee. + +## SHA512 Checksums + +Starting with v1.6.2, every rotki binary on the [releases page](https://github.com/rotki/rotki/releases) ships with a matching `.sha512` file. Download both and run the platform-specific command below. + +### Linux + +```sh +cd ~/Downloads +sha512sum -c rotki-linux_x86_64-vx.x.x.AppImage.sha512 +# rotki-linux_x86_64-vx.x.x.AppImage: OK +``` + +### macOS + +```sh +cd ~/Downloads +shasum -a 512 -c rotki-darwin-vx.x.x.dmg.sha512 +# rotki-darwin-vx.x.x.dmg: OK +``` + +### Windows + +Open Command Prompt in the download folder and compute the hash: + +```sh +cd Downloads +certutil -hashfile rotki-win32-vx.x.x.exe SHA512 +``` + +The output will look like: + +```sh +SHA512 hash of rotki-win32-v1.6.2.exe: +a3e0d79724460f642245774ba1af4c7116dfde56503d134c688f406afff5339f70a84a0bdb2556bc0785931b11e2447e3ffcd116cdec9e8a50382ec0165788b4 +CertUtil: -hashfile command completed successfully. +``` + +Open the `.sha512` file with Notepad and confirm the hash matches the one above. + +### If the checksum doesn't match + +If the hashes don't match, you should see an error similar to: + +```sh +rotki-linux_x86_64-vx.x.x.AppImage: FAILED +sha512sum: WARNING: 1 computed checksum did NOT match +``` + +**Do not run the binary.** Re-download it from the official [releases page](https://github.com/rotki/rotki/releases) and try again. + +## Publisher Signature + +You can also confirm the publisher by inspecting the binary's digital signature: + +- **Windows** — right-click the installer and open **Properties → Digital Signatures**. The signer should be `Rotki Solutions GmbH`. +- **macOS** — right-click the app and choose **Get Info**. The copyright should read `Rotki Solutions GmbH`. + +## GitHub Artifact Attestations + +rotki uses **GitHub Artifact Attestations** to cryptographically link each released binary back to the commit and workflow that produced it. This provides protection against supply chain attacks by confirming that the binary was genuinely built from the expected repository, commit, and build environment. + +You can verify attestations with the [GitHub CLI](https://cli.github.com/manual/gh_attestation_verify): + +```sh +gh attestation verify ~/Downloads/rotki134.dmg --repo rotki/rotki +``` + +Expected output: + +``` +Loaded digest sha256:12bb7aa1cf8d5b568f925e7c772b946a29efaf66ae030026a1f113da528c8e39 for file:///Users/you/Downloads/rotki134.dmg +Loaded 1 attestation from GitHub API +✓ Verification succeeded! + +sha256:12bb7aa1cf8d5b568f925e7c772b946a29efaf66ae030026a1f113da528c8e39 was attested by: +REPO PREDICATE_TYPE WORKFLOW +rotki/rotki https://slsa.dev/provenance/v1 .github/workflows/rotki_release.yaml@refs/tags/v1.34.0 +``` + +> [!WARNING] +> GitHub artifact attestations will fail for Windows binaries (`rotki-win32_x64-*.exe`) published after August 2025. These binaries are re-signed locally using a hardware key (Yubikey) with an OV Certificate, which causes the binary hash to change after attestation. For Windows binaries after that date, verify that the binary is signed by **Rotki Solutions GmbH** instead. diff --git a/usage-guides/advanced/mobile.md b/usage-guides/advanced/mobile.md index 0daa0cf..09671c9 100644 --- a/usage-guides/advanced/mobile.md +++ b/usage-guides/advanced/mobile.md @@ -18,7 +18,7 @@ This way you can get the full rotki functionality on mobile. ## Docker -Accessing rotki on mobile when you run Docker on your own can be a bit complicated and depends on the kind of setup you have. You have to make sure that [rotki is never directly accessible from a public network](/requirement-and-installation/packaged-binaries#docker). +Accessing rotki on mobile when you run Docker on your own can be a bit complicated and depends on the kind of setup you have. You have to make sure that [rotki is never directly accessible from a public network](/requirement-and-installation/docker). One way to have rotki accessible on mobile over a public network is by making sure that an [authenticated proxy](#docker-rotki-public) intercepts all traffic directed to rotki. This way you can ensure that no one else can access your rotki instance. From 698d12f1c8bbdb4a8d88a438ca7b27d0bf68f303 Mon Sep 17 00:00:00 2001 From: Konstantinos Paparas Date: Fri, 10 Apr 2026 14:48:09 +0200 Subject: [PATCH 3/3] chore: whitelist 'Sur' in typos config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit False positive — 'Big Sur' is the macOS 11 codename, not a typo for 'Sure'. Used in requirement-and-installation/index.md in the minimum system requirements table. --- _typos.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/_typos.toml b/_typos.toml index 4ffcb98..31f007b 100644 --- a/_typos.toml +++ b/_typos.toml @@ -12,3 +12,4 @@ extend-ignore-re = [ [default.extend-words] teh = "teh" # example variable +Sur = "Sur" # macOS Big Sur