Installation

Requirements#

ItemRequirement
Operating systemDebian 12 or 13, Ubuntu 22.04 or 24.04
Architectureamd64 or arm64
C librarylibc6 2.34 or newer
Init systemsystemd
Packagesadduser and ca-certificates (installed automatically as dependencies)
Reverse proxynginx, Caddy, HAProxy or another proxy that terminates TLS
NetworkOutgoing 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#

PathContents
/usr/bin/stacklaneThe server and command line tool
/etc/stacklane/stacklane.tomlConfiguration file (a configuration file in the Debian sense: upgrades keep your changes)
/etc/stacklane/secret.keySecret key, created on the first installation
/var/lib/stacklane/Data directory with the SQLite database
stacklane.serviceThe systemd unit
/usr/share/doc/stacklane/README.mdThe project README

What the post-install script does#

On every installation and upgrade, the post-install script:

  1. Creates the system group stacklane and the system user stacklane if they do not exist. The user has the home directory /var/lib/stacklane and no login shell.
  2. Creates /var/lib/stacklane with mode 0750, owned by stacklane:stacklane.
  3. Sets /etc/stacklane to mode 0750, owned by root:stacklane.
  4. Sets /etc/stacklane/stacklane.toml to mode 0640, owned by root:stacklane.
  5. Creates /etc/stacklane/secret.key with stacklane keygen if the file does not exist. The key is owned by stacklane:stacklane with mode 0600.
  6. Runs stacklane migrate as the stacklane user to create or update the database.
  7. 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:

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:

  1. Creates the secret key if it does not exist yet.
  2. Creates or updates the database.
  3. Asks for the email address, full name, organization name and password of the platform owner. The password must be 10 to 128 characters long.
  4. 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.

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#

LimitValue
Maximum request body256 KiB
Request timeout30 seconds
Concurrent requests1024; 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#

  1. Open https://panel.example.com/auth/sign-in.
  2. Sign in with the owner account you created with stacklane setup.
  3. Set up two-factor authentication in your account settings.
  4. Open the back office at https://panel.example.com/admin.

Next steps#

  1. Fill in your brand, support email and sign-up rules in Administration → Platform settings. Public sign-up is allowed by default.
  2. Add your company details, tax rules and payment methods in Administration → Billing settings.
  3. Connect the services you sell: Proxmox regions, panel servers and hosting plans, the registrar and PowerDNS. See Administration.
  4. Configure outgoing email if you have not done so yet. See Configuration.
  5. Plan your backups. See Operations.
  6. If you move from WHMCS, read Migrating from WHMCS.
  7. Read the Security recommendations.