Configuration
Overview#
Stacklane reads one configuration file in TOML format. The default path is /etc/stacklane/stacklane.toml. The file contains only what Stacklane needs to start: the listen address, the public URL, file paths, session lifetimes, email and the simulation switches.
Most business settings are not in this file. You set them in the back office under Administration, and Stacklane stores them in the database. Examples:
- brand, support email and sign-up rules
- company details, invoice numbering, payment terms and tax rules
- payment providers (Mollie, Stripe, PayPal, bank transfer)
- Proxmox regions, flavors and images
- hosting panel servers and plans
- the registrar, extensions and prices
- PowerDNS
- the DDoS webhook secret
Secrets you enter there are encrypted with the secret key. See Administration.
Rules for the file#
-
Every section and every key is optional. A missing key uses its default value. An empty file is valid.
-
Unknown sections and unknown keys are an error. A typing mistake in a key name stops Stacklane from starting.
-
Stacklane reads the file when a command starts. After a change, restart the service:
sudo systemctl restart stacklane -
Check the file with
sudo -u stacklane stacklane check. An invalid file gives an error such asinvalid configuration in /etc/stacklane/stacklane.toml: ....
Default file#
The package installs this file:
[server]
listen = "127.0.0.1:8080"
public_url = "http://localhost:8080"
behind_proxy = false
[database]
path = "/var/lib/stacklane/stacklane.db"
[security]
secret_key_file = "/etc/stacklane/secret.key"
access_token_minutes = 10
session_days = 30
[mail]
from = "Stacklane <no-reply@localhost>"
[cloud]
simulate = false
[billing]
simulate = false
Reference#
server#
| Key | Type | Default | Description |
|---|---|---|---|
listen | string (IP address and port) | "127.0.0.1:8080" | Address the HTTP server binds to. |
public_url | string (URL) | "http://localhost:8080" | External address of the panel. Must use http or https. |
behind_proxy | boolean | false | Read the client IP address from proxy headers. |
listen#
The value must be an IP address and a port, for example "127.0.0.1:8080" or "[::1]:8080". A host name such as localhost:8080 is not valid.
Stacklane serves plain HTTP. Keep it on a loopback address and put a reverse proxy with TLS in front of it. See Installation.
public_url#
Set this to the address your customers type in the browser, for example "https://panel.example.com". Stacklane uses it:
- to build links in emails (email verification, password reset, invitations, tickets, invoices)
- to build the return and webhook addresses for payment providers
- to show the DDoS webhook address in the back office
- to check the
Originheader on session refresh and sign-out - to decide if the refresh cookie is
Secureand uses the__Host-prefix (only forhttps) - to decide if the
Strict-Transport-Securityheader is sent (only forhttps)
Use https in production. With http, stacklane check prints warn public_url is not https; cookies are not marked secure.
behind_proxy#
When true, Stacklane takes the client address from the last entry of X-Forwarded-For. If that is missing, it uses X-Real-IP. If both are missing, it uses the address of the connection.
Enable this only when every request comes through your reverse proxy. Otherwise clients can send their own header and fake their address.
database#
| Key | Type | Default | Description |
|---|---|---|---|
path | string (file path) | "/var/lib/stacklane/stacklane.db" | Location of the SQLite database. |
Stacklane creates the file and its parent directory if they do not exist. The database runs in WAL mode, so you also see stacklane.db-wal and stacklane.db-shm next to it.
The systemd unit only allows writes to /var/lib/stacklane. If you move the database outside that directory, the service cannot write to it.
security#
| Key | Type | Default | Valid range | Description |
|---|---|---|---|---|
secret_key_file | string (file path) | "/etc/stacklane/secret.key" | File with the secret key. | |
access_token_minutes | integer | 10 | 1 to 60 | Lifetime of an access token in minutes. |
session_days | integer | 30 | 1 to 365 | How many days a sign-in stays valid. |
secret_key_file#
The secret key is 32 random bytes, stored as 64 hexadecimal characters. stacklane keygen creates it with mode 0600. Stacklane uses the key to:
- sign access tokens
- encrypt secrets in the database: Proxmox tokens, panel credentials, registrar passwords, payment provider keys, the PowerDNS API key, the DDoS webhook secret and two-factor secrets
Back up the key together with the database. Without the key, Stacklane cannot decrypt these secrets.
access_token_minutes#
After sign-in, the browser gets a short-lived access token and a refresh cookie. When the access token expires, the browser uses the refresh cookie to get a new one. A shorter lifetime means more refresh requests. Signing out and password resets take effect at once, whatever the lifetime, because Stacklane checks the session on every request.
session_days#
A session can be refreshed for this many days after sign-in. After that, the user must sign in again.
mail#
| Key | Type | Default | Description |
|---|---|---|---|
from | string (mailbox) | "Stacklane <no-reply@localhost>" | Sender of all emails. |
smtp_url | string (URL) | not set | SMTP server to send email through. |
from#
Use a plain address (support@example.com) or a name with an address (Example Cloud <support@example.com>). An invalid value stops Stacklane from starting.
smtp_url#
Without smtp_url, Stacklane does not send email. It writes each message to the service log instead, with a warning. This is useful for testing, but customers will not get password reset links or invoices.
Examples:
[mail]
from = "Example Cloud <support@example.com>"
# TLS from the start, usually port 465
smtp_url = "smtps://user:password@smtp.example.com:465"
# STARTTLS, usually port 587
# smtp_url = "smtp://user:password@smtp.example.com:587?tls=required"
If the user name or password contains special characters such as @, : or /, write them percent-encoded, for example %40 for @.
The URL contains a password. The configuration file is readable only by root and the stacklane group.
cloud#
| Key | Type | Default | Description |
|---|---|---|---|
simulate | boolean | false | Use built-in simulators instead of real infrastructure. |
billing#
| Key | Type | Default | Description |
|---|---|---|---|
simulate | boolean | false | Approve payments without a payment provider. |
demo#
| Key | Type | Default | Description |
|---|---|---|---|
email | string | not set | Email address of the public demo account. |
password | string | not set | Password of the public demo account. |
Use this section only for a public demonstration, together with simulate mode. See Public demo.
Simulate mode#
Simulate mode lets you try Stacklane, or develop it, without real infrastructure or real payments. Never enable it on a production system.
With cloud.simulate = true, Stacklane uses in-memory simulators for:
- Proxmox VE (instances are not created on a real hypervisor)
- the hosting panels (cPanel/WHM, DirectAdmin, Pterodactyl)
- the domain registrar
- PowerDNS
With billing.simulate = true:
- payments are approved without contacting a payment provider
- VAT numbers are checked with a simple built-in rule instead of the EU VIES service
The simulators keep their state in memory. It is lost when Stacklane restarts. The records in the database stay.
When a switch is on, Stacklane logs a warning at start:
cloud.simulate is enabled; instances are not created on a real hypervisor
billing.simulate is enabled; payments are approved without a payment provider
Public demo#
A public demo lets anyone try the panel with a shared account. Run it on its own server or installation, with both simulate switches on, and never with real customer data.
[cloud]
simulate = true
[billing]
simulate = true
[demo]
email = "demo@example.com"
password = "try stacklane today"
When demo.email and demo.password are both set, the sign-in page shows a notice with the credentials and a button that fills them in. The password is visible to every visitor, so use one that you do not use anywhere else.
When demo.email is set, nobody can lock others out of that account through the web interface or the API:
- its password and two-factor authentication cannot be changed
- its role cannot be changed and it cannot be removed from its organization
- the organization's two-factor policy cannot be changed
The command line is not restricted. Create the account with stacklane user create, and use stacklane user password --password-stdin to set the password from a script.
Visitors can still change everything else. To start each day from the same state, keep a copy of the database and restore it on a schedule:
sudo -u stacklane stacklane backup /var/lib/stacklane/demo-seed.db
systemctl stop stacklane
install -o stacklane -g stacklane -m 0640 /var/lib/stacklane/demo-seed.db /var/lib/stacklane/stacklane.db
rm -f /var/lib/stacklane/stacklane.db-wal /var/lib/stacklane/stacklane.db-shm
systemctl start stacklane
Environment variables#
| Variable | Used by | Description |
|---|---|---|
STACKLANE_CONFIG | all commands | Path of the configuration file. Same as --config. The systemd unit sets it to /etc/stacklane/stacklane.toml. |
STACKLANE_LOG | all commands | Log filter. Default: info,tower_http=warn,sqlx=warn. |
STACKLANE_WHMCS_SECRET | stacklane import whmcs | WHMCS API secret. Same as --secret. |
The order for the configuration path is: the --config flag, then STACKLANE_CONFIG, then /etc/stacklane/stacklane.toml. The file must exist, or the command stops with configuration file ... not found.
STACKLANE_LOG#
STACKLANE_LOG uses the filter syntax of the Rust tracing library: a default level, and optionally a level per component, separated by commas. Levels are error, warn, info, debug and trace.
| Value | Effect |
|---|---|
info,tower_http=warn,sqlx=warn | Default. Normal messages, no per-request logs. |
info,tower_http=debug | Also log every HTTP request. |
debug | Detailed logs from all components. |
warn | Only warnings and errors. |
To set it for the service, see Operations.
Production example#
[server]
listen = "127.0.0.1:8080"
public_url = "https://panel.example.com"
behind_proxy = true
[database]
path = "/var/lib/stacklane/stacklane.db"
[security]
secret_key_file = "/etc/stacklane/secret.key"
access_token_minutes = 10
session_days = 30
[mail]
from = "Example Cloud <support@example.com>"
smtp_url = "smtps://panel%40example.com:password@smtp.example.com:465"
[cloud]
simulate = false
[billing]
simulate = false