soldermaskdocs

Running in production

The app server is ready for production as it ships. There is no separate development mode to switch off.

About: what is running, and whether the machine can build

What the server does

soldermask serve runs the app under Hypercorn.

AreaWhat it does
ServingTLS with a self-signed certificate for the LAN address, or your own behind a proxy. HTTP/2 and keep-alive.
ShutdownGraceful. Every event stream gets a bye event, and shutdown takes about a second.
BuildsRun as jobs in a bounded thread pool (--workers, default 2). A request never waits on the model or the router.
CachingThe versioned static bundle is cached as immutable. Version files are cached for a day. Pages and API answers are no-store.
CompressionJSON and HTML are gzipped.
No third-party requeststhree.js and the fonts are vendored, so the app works on a LAN with no internet. The standalone export uses CDNs, because it must be one file.
HardeningA Content-Security-Policy with a nonce per request, HSTS on TLS, X-Content-Type-Options, X-Frame-Options and Referrer-Policy.
LimitsAn 8 MB request body, a 20,000-character message, and a five-strike lockout on the login page. One route takes more: a project zip on POST /api/projects/import, up to 256 MB, from a client the access rule already lets in.
Access controlOn by default. See Access control.
ObservabilityA timed access log (sync traffic left out), Server-Timing on every response, /api/health and /about.

/api/health never touches git or the disk, so it is safe to poll. /about shows the full picture, including whether the machine can build.

The one constraint

Run one server process per data directory. Jobs, the event bus and the per-project locks live in memory.

  • Do not run two servers against the same projects/.
  • Do not put a multi-worker WSGI server in front of it.

To scale, give each team or workspace its own directory and port.

Resources

A build places and routes the board. The first time a part is used, it also fetches the part's footprint and 3D model. Under soldermask serve, the heavy work runs outside the server's own process:

  • The placer anneals its placements in worker processes, one per core.
  • Lightcycle routes each whole board in a process of its own. A route still running after 600 seconds is stopped, and the gaps say so.
  • A short board's retries under other settings are solved ahead in worker processes, one per core. The copper is the same as solving them in turn.
  • On 32 cores or more, three placements are routed at once, each in its own process. Below that, they are routed one at a time.

--workers sets how many builds run at once. Each build reaches for every core, so two builds at once share the machine. These settings cap one build:

SettingDefault under serveSets
SOLDERMASK_ANNEAL_WORKERSOne per corePlacements annealed at once
SOLDERMASK_ROUTE_WORKERS3 on 32 cores or more, else 1Placements routed at once
SOLDERMASK_ROUTER_RETRY_WORKERSOne per coreRetries of a short board solved at once
SOLDERMASK_ROUTER_WALL_S600Seconds a whole-board route may run before it is stopped. 0 turns the limit off, and the route then runs in the build's own process.

See Configuration for the rest.

The cache

The cache directory holds what a build fetched. Some of it is slow or costly to fetch again. soldermask setup --check prints where the directory is.

In the cacheIf you delete it
access-tokenA new token is made. Every phone and script must log in again.
lan-cert.pem, lan-key.pemA new certificate is made. Each phone accepts the warning again.
kicad-symbols/No pin is checked against a KiCad symbol until soldermask setup fetches them again.
krt/The A* router is gone until soldermask setup --astar builds it again.
jlcapi/, jlcparts/, params.dbThe parts catalogue. A build fetches what it needs as it goes. soldermask setup --parts takes the whole catalogue again, which from JLCPCB's API takes over an hour.
components/Records the datasheet reader wrote. Reading a sheet again is billed again.
Footprints, 3D models, parts lookupsFetched again as builds need them.

Run soldermask setup after clearing the cache.

Logs

Logs go to stderr, or to a file with --log-file PATH. An access line looks like this:

2026-09-01 10:19:17 INFO  hypercorn.access: 127.0.0.1:51817 "POST /api/projects/x/chat 2" 202 512 11342us

Job starts, finishes and failures, with tracebacks, are logged under soldermask.jobs.

Upgrading

  1. Pull the new code, or run uv tool upgrade soldermask for a tool install.
  2. From a checkout, run pip install -e . and pip install ./mould in the server's environment.
  3. Run soldermask setup. It reinstalls Lightcycle when the version this soldermask pins has changed.
  4. Restart the server.
  5. Open /about. Check it names the version you expect, whether it is tagged, and the Lightcycle version.
  6. Optionally, run soldermask projects rejudge. It judges every saved version's copper again with today's DRC, and rewrites the verdicts that change. --dry-run only says what would change.

Projects written by an older layout are migrated the first time they are read. A copy of the old project.json is left beside it. See Projects on disk.

On this page