Deploying
These recipes start soldermask at boot on macOS or Linux, or run it behind nginx. A template for each is in the deploy folder.
Before you start
A service needs what any install needs. Do these in the environment the service will run.
- Install soldermask, as in Install.
- Install KiCad on the machine. Without
kicad-cli, no routed board can be GO. - Run
soldermask setupfrom that environment. It downloads Lightcycle withghsigned in, or withGH_TOKENset to a token that can readsoldermask-org/lightcycle. - Choose the design backend, below.
Choose the design backend
| Backend | The service needs |
|---|---|
| Claude Code (the default) | claude on the service's PATH, logged in to claude.ai once as the user the service runs as |
| Gemini | SOLDERMASK_BACKEND=gemini and GEMINI_API_KEY in its environment, and the Gemini SDK installed (the gemini extra) |
launchd and systemd start a service with a short PATH. It does not include
~/.local/bin, where claude is often installed. Each template sets PATH
for Claude Code and carries the Gemini lines commented out. /about says
whether the model is reachable.
macOS: start at login
deploy/com.soldermask.serve.plist is a launchd agent.
-
Open the file and replace every
/PATH/TO/soldermaskandYOU. -
Keep the
PATHline for Claude Code, or uncomment the Gemini lines and set the key. -
Install and load it:
cp deploy/com.soldermask.serve.plist ~/Library/LaunchAgents/ launchctl load ~/Library/LaunchAgents/com.soldermask.serve.plist -
Watch the log. You should see the banner, the QR code and then the access log:
tail -f ~/Library/Logs/soldermask.log
KeepAlive restarts the server if it dies.
Linux: systemd
deploy/soldermask.service runs the app as its own soldermask user, from a
checkout at /opt/soldermask, with SOLDERMASK_HOME=/var/lib/soldermask. It
restarts on failure and applies the usual hardening: NoNewPrivileges,
PrivateTmp, and ProtectSystem=full, which keeps /usr, /boot and /etc
read-only.
-
Create a
soldermaskuser for the service. Put a checkout at/opt/soldermaskwith its.venv, as in Install from a checkout. Install KiCad from theppa:kicad/kicad-10.0-releasesPPA. -
Run
setupwith the service's data directory, as a user that can write to the.venv. Then hand the data directory to the service user:sudo env SOLDERMASK_HOME=/var/lib/soldermask GH_TOKEN=<token> /opt/soldermask/.venv/bin/soldermask setup sudo chown -R soldermask: /var/lib/soldermask -
Choose the backend in the unit's
Environment=lines. For Claude Code, install it for thesoldermaskuser and log in once as that user. -
Install and start it:
sudo cp deploy/soldermask.service /etc/systemd/system/ sudo systemctl daemon-reload && sudo systemctl enable --now soldermask -
Watch the log:
journalctl -u soldermask -f
Behind nginx
deploy/nginx.conf terminates TLS with a real certificate and passes requests
to the app over plain HTTP.
-
Install the config. Keep its two lines for the event stream:
proxy_buffering offand the longproxy_read_timeout. -
Run the app on plain HTTP on the loopback address, trusting the proxy:
soldermask serve --http --host 127.0.0.1 --port 8080 --proxy
--proxy trusts the forwarded headers and requires the token from everyone,
because every request now looks local. See Access control.
--host 127.0.0.1 keeps the plain-HTTP port off the network. The server
listens on every address unless told otherwise.
Importing large projects through nginx
The config caps a request at 8 MB, as the app does. Its
/api/projects/import block raises that to 256 MB for a project zip. The
app takes a zip that large only from a request with the token or the
login cookie.
Containers
No container image is shipped. An image would need KiCad for the DRC, and a
token that can read soldermask-org/lightcycle when soldermask setup runs.
The app has not been tested in a container. On Linux, use the systemd unit.
Backups
- Back up
projects/. It holds the boards. The files are plain. - Copy it while the server runs if you like. Every write is atomic.
- Most of the cache can be fetched again with
soldermask setup. Two things cannot: the access token, and any datasheet records the reader was paid to write. See The cache.