F. TLS + credentials

The web UI is served over HTTPS and asks you to sign in. This step creates the two things that makes possible: a TLS certificate so the browser can open a secure connection, and a login account so you can authenticate.

Requires: Configure (step D)

Both commands read settings from the .env and config.yaml you set up in D. Configure — the certificate paths, the server name, and the password salt. Complete step D first.

Windows: use Git Bash

All make commands must be run in Git Bash, not PowerShell or cmd.exe.

1. Generate the TLS certificate

make ssl

This creates a self-signed certificate and private key and writes them into your certificates directory (PIPELINE_SSL_DIR, default ./data/certs):

File .env variable Default name
Certificate PIPELINE_SSL_CERT server.crt
Private key PIPELINE_SSL_KEY server.key

The certificate is issued for the host name in PIPELINE_SERVERNAME (default localhost) and is valid for one year.

PIPELINE_SSL_CERT / PIPELINE_SSL_KEY are filenames, never paths

Both variables are resolved against PIPELINE_SSL_DIR at every point of use — by make ssl, by make doctor, and by the running web service, which reads them as filenames inside its /certs mount. A value containing / — for example PIPELINE_SSL_CERT=${PIPELINE_SSL_DIR}/server.crt — doesn’t just fail make doctor, it breaks certificate generation and the running site too, since the value gets joined onto PIPELINE_SSL_DIR a second time. Keep both values as bare filenames, e.g. server.crt. (These two are the exception — see host paths vs container paths in D. Configure for how every other PIPELINE_* path variable behaves.)

2. Create your login

make gen-credentials

This prompts for a password and creates the account admin. It writes a hashed credentials file to credentials.json in the repository root (the path in PIPELINE_CREDENTIALS_FILE, default ./credentials.json) — your password is never stored in plain text.

To set the password without an interactive prompt (for example in a script), pass PASSWORD=:

make gen-credentials PASSWORD=your-password-here
The salt must already be set — and never change afterwards

make gen-credentials mixes your password with the salt from config.yaml before hashing. If you change that salt after generating credentials, every stored password becomes invalid and you’ll be locked out. Rotate the salt once in D. Configure, then leave it alone.

Already have the stack running? Both files need a restart to take effect

Re-running make ssl or make gen-credentials after make up isn’t picked up on its own — see When do I need to restart? for the command and why.

If something goes wrong

  • doctor says the cert or key is missing. Re-run make ssl and check that PIPELINE_SSL_DIR, PIPELINE_SSL_CERT, and PIPELINE_SSL_KEY in .env match the files that were created.
  • make ssl fails, or a path shows up doubled, e.g. ./data/certs/./data/certs/. PIPELINE_SSL_CERT or PIPELINE_SSL_KEY holds a path instead of a bare filename — see the callout above. Fix it to a filename (e.g. server.crt) and re-run make ssl.
  • doctor rejects PIPELINE_SSL_CERT or PIPELINE_SSL_KEY outright. It fails with a message like PIPELINE_SSL_CERT must be a filename only, not a path. Same fix as above — and don’t skip doctor before make up even if make ssl succeeded, since the same value breaks the running web service too, just later.
  • doctor says the credentials file is missing. Re-run make gen-credentials. The file is written to the repo root by default; make sure PIPELINE_CREDENTIALS_FILE in .env points at it.
  • You can’t log in even though the files exist. The password was almost certainly hashed with a different salt than the app is using. Set the salt in config.yaml first, then re-run make gen-credentials so the hash matches.