Run a server
A Nether server syncs vaults between devices, shares them with other
people and serves the web app. One docker compose up starts it with
everything it needs: PostgreSQL for its data, Valkey for its rate limits,
and a volume for attachments and backups. To run it on Kubernetes, one
node or several, see Kubernetes and
High availability.
Start it
Section titled “Start it”You need Docker with
Docker Compose 2.24 or later. Get the repository, and start the server
from its deploy/docker folder:
git clone https://github.com/fzn0x/nether.gitcd nether/deploy/dockerdocker compose up -dCompose pulls the server’s image, ghcr.io/fzn0x/nether-server, or builds
it from the repository when it cannot pull it. Once a release has
published the image, the docker-compose.yml file alone is enough: copy
it into a folder of its own and run docker compose up -d there.
The server answers on http://127.0.0.1:3000, on this machine only, until
you choose otherwise below.
Set it up
Section titled “Set it up”A new server has no account. Its log has a code that makes the first one, the server’s admin, with a first workspace:
docker compose logs server | grep "Set it up"Open the server’s web app, http://127.0.0.1:3000, and choose Sign
in; or, in the desktop app, run Servers and signing in and type the
server’s address. Either asks for the setup code, then your name, email
address, password (twelve characters or more) and the first workspace’s
name, and signs you in as the server’s admin. Then invite the others from
Workspace members, as the servers guide shows.
The code works once. Only someone who can read the server’s log can set it
up, so a new server cannot be claimed by whoever finds it first. To choose
the code yourself, set NETHER_SETUP_CODE in the server’s environment, as
openssl rand -hex 12 makes one; the log then says only that the server
waits for setup. A server of several nodes needs it, so each accepts the
same code. Without
an app at hand, POST /api/setup does the same:
curl -X POST http://127.0.0.1:3000/api/setup -H 'content-type: application/json' \ -d '{"code":"ABCDE-FGHJK-LMNPQ-RSTUV","name":"Ada","email":"ada@example.org", "password":"at least twelve characters","workspace":"Team"}'Put it behind HTTPS
Section titled “Put it behind HTTPS”Browsers keep the web app’s sessions and run its offline copy only over
HTTPS, and passwords should never cross a network in the clear. Put a
reverse proxy in front of the server, on the same machine. With
Caddy, which fetches its certificate on its
own, this Caddyfile does it:
nether.example.org { reverse_proxy 127.0.0.1:3000}Then tell the server its address, and to believe the proxy about each
client’s address, in a .env file beside docker-compose.yml:
NETHER_PUBLIC_URL=https://nether.example.orgNETHER_TRUST_PROXY=uniquelocaluniquelocal believes any private address. It is safe while the server is
published on 127.0.0.1 alone, as it is by default, since only the proxy
on this machine reaches it then. The proxy passes WebSocket connections
through, which sync uses, on the same port.
Published sites are served at the same address, under
/p/, so the proxy needs nothing more for them, and NETHER_PUBLIC_URL
is the address the app copies for them.
Custom domains for published sites
Section titled “Custom domains for published sites”A published site can be put on a domain of its own, which the person publishing it proves with a TXT record. The server then answers that domain’s requests with the site. The proxy needs a certificate for each such domain, and Caddy’s on-demand TLS gets one the first time the domain is asked for, after asking the server whether a site holds it:
{ on_demand_tls { ask http://127.0.0.1:3000/api/sites/domain }}
nether.example.org { reverse_proxy 127.0.0.1:3000}
https:// { tls { on_demand } reverse_proxy 127.0.0.1:3000}Caddy adds ?domain= and the name to the ask address. The server
answers 200 only for a domain a published site holds, so Caddy gets no
certificate for any other name pointed at the machine. The proxy keeps
the request’s host, which is how the server knows the site; keep
NETHER_TRUST_PROXY set as above.
Each site’s owner points their domain at this machine with an A or
CNAME record, beside the TXT record that proves it. Keep
NETHER_PUBLIC_URL set: its host stays the server’s own, and no site can
take it.
Settings
Section titled “Settings”Settings go in the .env file beside docker-compose.yml, one
NAME=value a line, and take effect when the server starts again:
docker compose up -d. Three are Compose’s own:
| Setting | Default | |
|---|---|---|
NETHER_PUBLISH |
127.0.0.1:3000 |
The address and port on this machine the server answers at; 0.0.0.0:3000 for every network it is on |
NETHER_VERSION |
latest |
The image’s version, as 0.2.0, to stay on one release |
NETHER_POSTGRES_PASSWORD |
nether |
PostgreSQL’s password, read when its volume is first made; set it before the first start |
The server reads every other setting of the server’s configuration from the same file, such as:
- Email, for codes that sign in and mentions:
NETHER_SMTP_URL=smtp://user:password@mail.example.org:587andNETHER_MAIL_FROM=Nether <nether@example.org>. - Single sign-on with your OpenID Connect provider:
NETHER_OIDC_ISSUER,NETHER_OIDC_CLIENT_IDandNETHER_OIDC_CLIENT_SECRET, withNETHER_PUBLIC_URLset. SAML 2.0 providers, and more OpenID Connect ones, are added in the admin console, which needsNETHER_SECRET_KEYtoo. They reach public addresses only:NETHER_SSO_PRIVATE=loopback, or an address or range, lets them be on your own network, as Keycloak beside the server. Where the console requires single sign-on and a provider breaks,NETHER_SSO_ENFORCE=offlets everyone in another way again. - An LDAP directory to provision from, as Active Directory, added in
the admin console with
NETHER_SECRET_KEYset, which seals its bind password. It reaches public addresses only:NETHER_LDAP_PRIVATE=10.0.0.0/8, or another address or range, lets the server read a directory on your own network. - Attachments in an S3-compatible bucket instead of the volume:
NETHER_STORAGE=s3withNETHER_S3_ENDPOINT,NETHER_S3_BUCKET,NETHER_S3_ACCESS_KEYandNETHER_S3_SECRET_KEY. - Scheduled backups:
NETHER_BACKUP=disk, below. - Webhooks to your own network: webhooks reach public addresses only.
NETHER_WEBHOOK_PRIVATE=192.168.1.20lets them reach that one, or a range as10.0.0.0/8, oronany; those may usehttp://. - AI in the web app, through the server:
NETHER_SECRET_KEY, made withopenssl rand -base64 32, lets the server keep providers’ keys, sealed with it. Keep it safe: a restored backup needs the same one to open them.NETHER_AI_PRIVATE=loopback, or an address or range, lets the providers you set for everyone reach a model on your own network, as Ollama beside the server; accounts’ own providers reach public addresses only.NETHER_AI=adminleaves only your providers, andNETHER_AI=offturns AI through the server off. See AI. - AI locked to your own endpoints: with Data policies on,
NETHER_AI_ENDPOINTS=https://llm.example.com/v1keeps every Nether app to that address for your server’s workspaces, or the admin console sets the list. See the admin console. - Enterprise features, each off until you turn it on in the
admin console:
NETHER_ENTERPRISE_AUDIT=on, oroff, sets that feature here instead, and the console shows it as set by its variable. The others areNETHER_ENTERPRISE_SSO,_SCIM,_POLICIES,_PERMISSIONSand_ADMIN. High availability,NETHER_ENTERPRISE_HA, is set here alone, for a server of several nodes.
Update it
Section titled “Update it”docker compose pulldocker compose up -dThe server brings its database to the new version’s schema as it starts.
Versions within one major release can be skipped. To choose when to move,
set NETHER_VERSION to a release and change it when you are ready.
As it stops, the server first answers 503 at /health/ready, so a load
balancer sends it nothing new, waits NETHER_DRAIN_SECONDS, then closes.
The apps connect again on their own. The Compose file sets the wait to 0,
since its one node has no other to take its traffic. Behind a load
balancer with several nodes, keep the default of 5 seconds, so each node
leaves the balancer before it closes. A server of the previous release
still runs on the new schema, so a server of several nodes can be
upgraded one node at a time.
Back it up
Section titled “Back it up”The server’s data is in two volumes: database, PostgreSQL’s, and
files, which holds the attachments and the server’s own backups. The
simplest backup is the server’s: one file holding the database and every
attachment, made while it runs. Add to .env:
NETHER_BACKUP=diskThe server then makes one a day in /data/backups, in the files
volume, and keeps the newest seven (NETHER_BACKUP_HOURS and
NETHER_BACKUP_KEEP change that). To make one now, and copy it off this
machine, where a backup belongs:
docker compose exec server node dist/admin.js backup /data/backups/now.ndjson.gzdocker compose cp server:/data/backups/now.ndjson.gz .Restore it
Section titled “Restore it”A backup restores into a new, empty server, on this machine or another,
from the server that made it or an older one of the same major release.
With the backup in the current folder, as nether.ndjson.gz:
docker compose down --volumes # only on this machine: deletes the server's datadocker compose run --rm --volume "$PWD:/restore:ro" server \ node dist/admin.js restore /restore/nether.ndjson.gzdocker compose up -dThe first line deletes the database and files volumes, so be sure the backup is outside them first. The restore refuses a database that has data, so it never overwrites one by mistake. Accounts, sessions, workspaces, notes and attachments come back as they were when the backup was made. CI runs these steps on every change.