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:

Secrets you enter there are encrypted with the secret key. See Administration.

Rules for the file#

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#

KeyTypeDefaultDescription
listenstring (IP address and port)"127.0.0.1:8080"Address the HTTP server binds to.
public_urlstring (URL)"http://localhost:8080"External address of the panel. Must use http or https.
behind_proxybooleanfalseRead 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:

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#

KeyTypeDefaultDescription
pathstring (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#

KeyTypeDefaultValid rangeDescription
secret_key_filestring (file path)"/etc/stacklane/secret.key"File with the secret key.
access_token_minutesinteger101 to 60Lifetime of an access token in minutes.
session_daysinteger301 to 365How 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:

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#

KeyTypeDefaultDescription
fromstring (mailbox)"Stacklane <no-reply@localhost>"Sender of all emails.
smtp_urlstring (URL)not setSMTP 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#

KeyTypeDefaultDescription
simulatebooleanfalseUse built-in simulators instead of real infrastructure.

billing#

KeyTypeDefaultDescription
simulatebooleanfalseApprove payments without a payment provider.

demo#

KeyTypeDefaultDescription
emailstringnot setEmail address of the public demo account.
passwordstringnot setPassword 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:

With billing.simulate = true:

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:

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#

VariableUsed byDescription
STACKLANE_CONFIGall commandsPath of the configuration file. Same as --config. The systemd unit sets it to /etc/stacklane/stacklane.toml.
STACKLANE_LOGall commandsLog filter. Default: info,tower_http=warn,sqlx=warn.
STACKLANE_WHMCS_SECRETstacklane import whmcsWHMCS 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.

ValueEffect
info,tower_http=warn,sqlx=warnDefault. Normal messages, no per-request logs.
info,tower_http=debugAlso log every HTTP request.
debugDetailed logs from all components.
warnOnly 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