Installation
Requirements#
| Item | Requirement |
|---|---|
| Operating system | Debian 12 or 13, Ubuntu 22.04 or 24.04 |
| Architecture | amd64 or arm64 |
| C library | libc6 2.34 or newer |
| Init system | systemd |
| Packages | adduser and ca-certificates (installed automatically as dependencies) |
| Reverse proxy | nginx, Caddy, HAProxy or another proxy that terminates TLS |
| Network | Outgoing access to the services you connect: Proxmox VE, hosting panels, Openprovider, PowerDNS, payment providers and your SMTP server |
Stacklane has no other runtime dependencies. The database is an embedded SQLite file and the web interface is built into the binary.
Payment providers and your DDoS detector send webhooks to Stacklane. The panel must be reachable for them at the address you set in server.public_url.
Install the package#
Copy the .deb file for your architecture to the server and install it with apt:
sudo apt install ./stacklane_0.1.0-1_amd64.deb
Use the arm64 file on arm64 servers. Use ./ in front of the file name, so apt installs the local file and resolves its dependencies.
What the package installs#
| Path | Contents |
|---|---|
/usr/bin/stacklane | The server and command line tool |
/etc/stacklane/stacklane.toml | Configuration file (a configuration file in the Debian sense: upgrades keep your changes) |
/etc/stacklane/secret.key | Secret key, created on the first installation |
/var/lib/stacklane/ | Data directory with the SQLite database |
stacklane.service | The systemd unit |
/usr/share/doc/stacklane/README.md | The project README |
What the post-install script does#
On every installation and upgrade, the post-install script:
- Creates the system group
stacklaneand the system userstacklaneif they do not exist. The user has the home directory/var/lib/stacklaneand no login shell. - Creates
/var/lib/stacklanewith mode0750, owned bystacklane:stacklane. - Sets
/etc/stacklaneto mode0750, owned byroot:stacklane. - Sets
/etc/stacklane/stacklane.tomlto mode0640, owned byroot:stacklane. - Creates
/etc/stacklane/secret.keywithstacklane keygenif the file does not exist. The key is owned bystacklane:stacklanewith mode0600. - Runs
stacklane migrateas thestacklaneuser to create or update the database. - Enables and starts
stacklane.service. On an upgrade, it restarts the service.
After the first installation the script prints the next steps:
Stacklane is installed.
1. Set server.public_url in /etc/stacklane/stacklane.toml
2. Create the platform owner: sudo -u stacklane stacklane setup
3. Restart the service: sudo systemctl restart stacklane
The service is already running at this point, with the default configuration. It listens on 127.0.0.1:8080 and is not reachable from outside the server.
Set the public URL#
Open the configuration file:
sudo editor /etc/stacklane/stacklane.toml
Set public_url to the address your customers will use. If you run a reverse proxy on the same server, also set behind_proxy = true:
[server]
listen = "127.0.0.1:8080"
public_url = "https://panel.example.com"
behind_proxy = true
public_url is important. Stacklane uses it:
- to build links in emails, such as password reset and invitation links
- to build the webhook addresses for payment providers
- to check the
Originheader when a browser refreshes a session or signs out - to decide if cookies are marked
Secureand if Strict-Transport-Security is sent (only forhttps)
Use the exact address that appears in the browser, with the scheme and without a path. If the address in the browser is different, sessions cannot be refreshed and users are signed out when their access token expires.
While you edit the file, you can also set up outgoing email in the [mail] section. Without mail.smtp_url, emails are not sent but written to the service log. See Configuration for every key.
Create the platform owner#
Run the setup command as the stacklane user:
sudo -u stacklane stacklane setup
The command:
- Creates the secret key if it does not exist yet.
- Creates or updates the database.
- Asks for the email address, full name, organization name and password of the platform owner. The password must be 10 to 128 characters long.
- Creates the account and prints the sign-in address.
Stacklane 0.1.0
Panel address: https://panel.example.com/
Create the platform owner account.
Email address: owner@example.com
Full name: Example Owner
Organization name: Example Hosting
Password:
Repeat password:
Owner account created. Sign in at https://panel.example.com/auth/sign-in
The owner account has the platform staff role owner and is the administrator of its own organization. If an owner already exists, setup does not create another one. Use stacklane user to add more accounts.
Restart the service#
Restart Stacklane so it reads the new configuration:
sudo systemctl restart stacklane
Check that the configuration, the database and the email settings are correct:
sudo -u stacklane stacklane check
ok secret key
ok database (1 organizations)
ok smtp configured
A warn line does not stop Stacklane, but read it. A fail line means something must be fixed. See Operations for details.
Set up a reverse proxy#
Stacklane serves plain HTTP. Put a reverse proxy in front of it to terminate TLS. Keep server.listen on 127.0.0.1 so the HTTP port is not reachable from the internet.
How Stacklane reads the client address#
Stacklane uses the client IP address for rate limits, sign-in history, sessions and the audit log.
- With
behind_proxy = false, Stacklane uses the address of the TCP connection. - With
behind_proxy = true, Stacklane reads the last address in theX-Forwarded-Forheader. If that header is missing or invalid, it readsX-Real-IP. If both are missing, it uses the address of the TCP connection.
Set behind_proxy = true only when all traffic comes through your proxy. If clients can reach Stacklane directly, they can send their own headers and fake their address.
If you forget behind_proxy = true behind a proxy, every request seems to come from the proxy. All users then share the same rate limits and are blocked together.
Stacklane uses the last address in X-Forwarded-For, because that is the address your proxy adds. If another proxy or a CDN sits in front of your reverse proxy, configure your reverse proxy so the last address is still the real client, for example with the nginx realip module.
Stacklane already sends the security headers, the Content Security Policy and Strict-Transport-Security (when public_url uses https). It also compresses responses. You do not need to add these in the proxy. Do not rewrite the Origin header.
nginx#
server {
listen 80;
listen [::]:80;
server_name panel.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name panel.example.com;
ssl_certificate /etc/letsencrypt/live/panel.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/panel.example.com/privkey.pem;
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
}
}
$proxy_add_x_forwarded_for adds the client address at the end of the header, which is the address Stacklane reads. Get a certificate with your usual tool, for example certbot.
Reload nginx after you change the file:
sudo nginx -t && sudo systemctl reload nginx
Caddy#
Caddy gets and renews a certificate automatically. It also sets X-Forwarded-For to the client address by default.
panel.example.com {
reverse_proxy 127.0.0.1:8080
}
Reload Caddy after you change the Caddyfile:
sudo systemctl reload caddy
Limits to keep in mind#
| Limit | Value |
|---|---|
| Maximum request body | 256 KiB |
| Request timeout | 30 seconds |
| Concurrent requests | 1024; requests above this limit get 503 Service Unavailable |
The default limits of nginx and Caddy are larger than these. You do not need to change them.
First sign-in#
- Open
https://panel.example.com/auth/sign-in. - Sign in with the owner account you created with
stacklane setup. - Set up two-factor authentication in your account settings.
- Open the back office at
https://panel.example.com/admin.
Next steps#
- Fill in your brand, support email and sign-up rules in Administration → Platform settings. Public sign-up is allowed by default.
- Add your company details, tax rules and payment methods in Administration → Billing settings.
- Connect the services you sell: Proxmox regions, panel servers and hosting plans, the registrar and PowerDNS. See Administration.
- Configure outgoing email if you have not done so yet. See Configuration.
- Plan your backups. See Operations.
- If you move from WHMCS, read Migrating from WHMCS.
- Read the Security recommendations.