soldermaskdocs

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.

  1. Install soldermask, as in Install.
  2. Install KiCad on the machine. Without kicad-cli, no routed board can be GO.
  3. Run soldermask setup from that environment. It downloads Lightcycle with gh signed in, or with GH_TOKEN set to a token that can read soldermask-org/lightcycle.
  4. Choose the design backend, below.

Choose the design backend

BackendThe 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
GeminiSOLDERMASK_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.

  1. Open the file and replace every /PATH/TO/soldermask and YOU.

  2. Keep the PATH line for Claude Code, or uncomment the Gemini lines and set the key.

  3. Install and load it:

    cp deploy/com.soldermask.serve.plist ~/Library/LaunchAgents/
    launchctl load ~/Library/LaunchAgents/com.soldermask.serve.plist
  4. 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.

  1. Create a soldermask user for the service. Put a checkout at /opt/soldermask with its .venv, as in Install from a checkout. Install KiCad from the ppa:kicad/kicad-10.0-releases PPA.

  2. Run setup with 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
  3. Choose the backend in the unit's Environment= lines. For Claude Code, install it for the soldermask user and log in once as that user.

  4. Install and start it:

    sudo cp deploy/soldermask.service /etc/systemd/system/
    sudo systemctl daemon-reload && sudo systemctl enable --now soldermask
  5. 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.

  1. Install the config. Keep its two lines for the event stream: proxy_buffering off and the long proxy_read_timeout.

  2. 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.

On this page