One container, one folder
nexcrate brings its database along and needs nothing next to it. What you should decide beforehand is where the data lives and how nexcrate sees your media. Both are on this page.
Starting
You need Docker with Compose. The compose file from the repository pulls the ready image ghcr.io/derkezorm/nexcrate:latest.
mkdir nexcrate && cd nexcrate
curl -fsSL https://raw.githubusercontent.com/DerKezorm/nexcrate/main/docker-compose.yml -o docker-compose.yml
docker compose up -d
Before you start, look into the file: the line for your media is still commented out, and without it nexcrate sees not a single folder. How to set it is below under Media and hardlinks.
Then nexcrate is at http://your-host:8390. The container is called nexcrate and comes back by itself with restart: unless-stopped; restoring a backup, which ends with a restart, needs that too.
The account
On the first visit nexcrate asks for a username and a password. That is the only account there is. If you want to take wishes from others, put Nexview in front of it.
Whoever reaches a fresh installation first can claim it. Until the account exists, anybody who can open the page can create it. Create it right after the first start, before the port is reachable from other networks. Once the account exists, the setup route is closed for good.
Below the form there is Start from a backup. With it a new installation starts with the state of an old one instead of empty.
The language you create the account in is the language of the interface. You can switch it at the top right at any time.
The data directory
Everything that belongs to nexcrate itself lives in /data, that is ./data next to the compose file: the database, the key secret.key, the log and the backups under data/backups/.
/data belongs on a local disk, never on an SMB or NFS share. SQLite's locking does not work reliably over network file systems, and that is how it loses data. On a NAS use a path on an internal volume, not a mounted share.
Back up secret.key together with the database. Stored credentials, such as the keys of indexers and download clients, are encrypted with it; without the file they have to be entered again. A backup you download from nexcrate contains both.
Media and hardlinks
nexcrate files into folders it can see inside its container, and you choose them from a list. Nobody types a path. Mount the folder that holds your downloads and your media, for example:
volumes:
- ./data:/data
- /srv/data:/media
/data is nexcrate's own and is never offered as a media folder. So pick another path inside the container for your media, such as /media.
Hardlinks work only inside one mount. Keep the downloads of your download clients and your media folders below one host folder, such as /srv/data/torrents, /srv/data/usenet and /srv/data/movies, and mount that one folder. With two mounts, even of the same disk, every torrent is copied and takes its space twice.
Your download clients may see the same folder under another path, for example /data instead of /media. nexcrate notices that at the first finished download and asks you once how the paths belong together.
After adding a mount the container needs a restart, otherwise it does not see the folder.
Environment variables
All optional. The defaults are in .env.example and in the compose file.
| Variable | Default | Meaning |
|---|---|---|
PUID, PGID | 1000 | Who owns the files in the data directory. The container fixes the rights itself. |
NEXCRATE_SECRET_KEY | generated | Key for the stored credentials. Empty means nexcrate creates data/secret.key on the first start. |
NEXCRATE_COOKIE_SECURE | auto | auto follows the scheme of each request, on for a reverse proxy that ends TLS, off never. |
NEXCRATE_LOG_LEVEL | empty | Fixes the log mode: quiet, normal, detailed, trace. Meant for the case that nexcrate does not start at all. |
NEXCRATE_URL_BASE | empty | Serve nexcrate under a sub path such as /nexcrate. /api/health also answers at the root. |
NEXCRATE_PORT | 8390 | Port inside the container. |
NEXCRATE_DATA_DIR | /data | Where database, key, log and backups live. Inside the container there is rarely a reason to change it. |
Reverse proxy
nexcrate speaks plain HTTP inside. Behind a proxy that ends TLS, set NEXCRATE_COOKIE_SECURE=on so the session cookie only travels over HTTPS.
Do not set on if nexcrate is also opened over http://. The browser drops a secure cookie sent over HTTP, and then nobody stays logged in.
Under a sub path instead of a subdomain of its own: NEXCRATE_URL_BASE=/nexcrate, and the proxy passes the path through unchanged.
Updating
docker compose pull
docker compose up -d
When a new version changes the structure of the database, nexcrate makes a backup first. It then shows under Settings › System › Backups as "Before change".
Once a day nexcrate asks GitHub for the newest release and shows it. Nothing but the request itself goes out, and it can be switched off under Settings › About nexcrate.
Forgot the password
There is one account and no other way back in. Whoever controls the server sets a new one:
docker exec -it nexcrate python -m app.cli reset-password
It asks for the new password twice without showing it, and ends every session.
Next comes the setup, or switching over if Radarr, Sonarr or Lidarr are already running.