Skip to content

Document Docker security, session auth and image verification #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
kelsos wants to merge 7 commits into
base: develop
Choose a base branch
from
+296 −7
Draft

Document Docker security, session auth and image verification #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
e7c8723
docs: document session authentication for docker
kelsos Aug 11, 2026
b0bfd61
docs: restructure the docker security section
kelsos Aug 11, 2026
8de8586
docs: document docker image provenance and SBOM
kelsos Aug 11, 2026
a9a71a0
docs: recommend HSTS alongside the reverse proxy
kelsos Aug 11, 2026
22d441d
docs: document the Secure session cookie flag
kelsos Aug 12, 2026
486c0fb
docs: document the container health check and shutdown
kelsos Aug 19, 2026
595df66
docs: note the root-owned lock file under --user
kelsos Aug 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 36 additions & 1 deletion requirement-and-installation/build-from-source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -212,9 +212,44 @@ pnpm run dev:web
To build a Docker image from source using the repo's `Dockerfile`:

```sh
docker build -t rotki .
docker build \
--build-arg ROTKI_VERSION=1.44.0 \
--build-arg REVISION="$(git rev-parse HEAD)" \
-t rotki .
```

`ROTKI_VERSION` is not optional. It becomes the backend package's fallback version, and without it the build fails late, during the PyInstaller step, with `InvalidVersion: ''`. Use the version you are building, or any valid version string if you only want an image to test with. `REVISION` is only reported by the running image and can be left out.

### Debugging a container you built

The runtime image is distroless. It has no shell, no package manager and no coreutils, so the usual moves do not work:

```sh
docker exec rotki sh
# OCI runtime exec failed: exec failed: unable to start container process:
# exec: "sh": executable file not found in $PATH
```

`ls`, `cat` and friends fail the same way. What does work:

- `docker exec rotki /opt/rotki/starling ctl status` for the state of the supervised processes.
- `docker top rotki` for the process list.
- Reading the data and log volumes from the host side of the bind mount rather than from inside the container.

If you genuinely need a shell in there, build yourself a debug image. There is no published `:debug` tag, deliberately, so layer one on top of the image you just built:

```dockerfile
FROM rotki:latest
COPY --from=busybox:1.37-uclibc /bin/busybox /bin/busybox
```

```sh
docker build -t rotki:debug -f Dockerfile.debug .
docker exec -it rotki /bin/busybox sh
```

Inside that shell the applets are not on `PATH` as separate commands, so call them through busybox: `busybox ls /opt/rotki`, `busybox cat /logs/rotki.log`. Keep this for local debugging; do not run a busybox-carrying image in production, since it hands anything that gets in the shell the image was built without.

## Troubleshooting

### Blank screen when running the dev server
Expand Down
Loading