Development

This page explains how to build Stacklane from source, run it on your own machine, run the tests and build the Debian package.

Requirements#

ToolVersionUsed for
Rust1.88 or newer (edition 2024)The backend
Node.js22 or newer, with npmThe frontend
GNU MakeanyThe build targets
cargo-debanyBuilding the .deb package (only for make deb)

The repository does not pin a Rust toolchain. Continuous integration uses the latest stable Rust and Node.js 22.

Install cargo-deb once:

cargo install cargo-deb --locked

Make targets#

TargetWhat it does
make or make allSame as make deb.
make frontendInstalls the npm packages with npm ci and builds the portal into ngx-ui/dist/.
make backendBuilds the frontend, then builds the stacklane binary in release mode.
make debBuilds the frontend, then builds the binary and the .deb package into dist/.
make devStarts the Angular development server for the portal on port 4200.
make testRuns all Rust tests and the portal tests.
make lintChecks the Rust formatting and runs Clippy with warnings as errors.
make cleanRemoves the Rust build output, ngx-ui/dist and dist.
make siteBuilds the website in site/ into one binary at site/target/release/stacklane-site.
make site-devStarts the Vite development server for the website on port 5174.

Run Stacklane locally#

In development you run the backend with cargo run and the frontend with the Angular development server. The development server serves the portal on port 4200 and forwards /api to the backend on 127.0.0.1:8090.

  1. Install the frontend packages:

    cd ngx-ui && npm ci && cd ..
    
  2. Create a configuration file dev.toml in the root of the repository. Git ignores this file, the database and the key file.

    [server]
    listen = "127.0.0.1:8090"
    public_url = "http://localhost:4200"
    behind_proxy = false
    
    [database]
    path = "data/stacklane.db"
    
    [security]
    secret_key_file = "data/secret.key"
    
    [cloud]
    simulate = true
    
    [billing]
    simulate = true
    

    Relative paths are relative to the directory you run the command in. public_url points at the development server, because that is the address in your browser. The session refresh checks the Origin header against it.

  3. Create the secret key and the owner account:

    cargo run -- -c dev.toml keygen
    cargo run -- -c dev.toml setup
    
  4. Start the backend:

    cargo run -- -c dev.toml serve
    
  5. In a second terminal, start the frontend:

    make dev
    
  6. Open http://localhost:4200 and sign in.

cargo run builds and runs the stacklane binary.

Simulate mode#

With cloud.simulate = true, Stacklane uses in-memory simulators for Proxmox VE, the hosting panels, the registrar and PowerDNS. With billing.simulate = true, payments are approved at once and VAT numbers are checked with a simple built-in rule instead of VIES. You can then create instances, order hosting, register domains and pay invoices without any real infrastructure.

The simulators keep their state in memory. It is lost when you stop the backend. See Configuration.

Email in development#

Without mail.smtp_url, Stacklane writes every email to its log. Use this to open verification and password reset links while you develop.

More logging#

STACKLANE_LOG=debug cargo run -- -c dev.toml serve

Tests and checks#

Run everything that continuous integration runs:

make lint
make test

make lint runs:

cargo fmt --all --check
cargo clippy --all-targets -- -D warnings

make test runs:

cargo test
cd ngx-ui && npx ng test portal --watch=false

Run one test file or one module:

cargo test --test game
cargo test hosting::

The Rust tests use an in-memory SQLite database and the same in-memory simulators as simulate mode. They do not need Proxmox, hosting panels or network access. The end-to-end API tests are in tests/. The portal tests use Vitest.

Code style:

Project layout#

Backend#

The backend is one Rust crate in the repository root. The library in src/lib.rs holds every module; src/main.rs is the stacklane binary.

PathContents
src/main.rsThe stacklane binary and its command line
src/config.rs, crypto.rs, jwt.rs, model.rs, password.rs, validate.rs, vat.rsConfiguration, domain types, validation, VAT rules, password hashing, cryptography, JWT
src/storeSQLite persistence
src/apiHTTP API, authentication, rate limits, audit log, email and the embedded web interface
src/cloudProxmox VE client and the instance task worker
src/hostingcPanel/WHM, DirectAdmin and Pterodactyl clients, game server management, Minecraft catalog and the provisioning worker
src/domainsRegistrar clients, PowerDNS and the registration and renewal worker
src/billingPayment gateways, VIES checks, usage metering, invoicing and dunning
src/importWHMCS import
migrationsDatabase migrations, embedded in the binary
testsEnd-to-end tests

Each integration sits behind a trait. The modules contain a fake or simulator part with in-memory versions, used by the tests and by simulate mode.

Frontend projects#

The frontend is an Angular workspace in ngx-ui/.

ProjectPathContents
uingx-ui/projects/uiThe @stacklane/ui component library and design tokens
portalngx-ui/projects/portalThe customer portal and back office

Translations are JSON files in ngx-ui/projects/portal/public/i18n/. Every user-facing string goes through them. Add each new key to every language.

Other directories#

PathContents
packaging/Debian maintainer scripts, the systemd unit and the default configuration
docs/This documentation
site/The website with these docs, see Website
dist/Built .deb packages

Website#

The website, with the landing page and this documentation, lives in site/. It is a small Rust server (Axum) with a React frontend in site/web/, and it reads the Markdown files in docs/ at build time.

make site
STACKLANE_SITE_URL=https://example.com ./site/target/release/stacklane-site
VariableDefaultDescription
STACKLANE_SITE_LISTEN127.0.0.1:8081Address the server binds to.
STACKLANE_SITE_URLhttp:// plus the listen addressPublic address, used for canonical links and the sitemap.
STACKLANE_SITE_LOGinfo,tower_http=warnLog filter.

To work on it, run the binary with cargo run in site/ and make site-dev next to it. Vite serves the frontend on port 5174 and forwards /api and /docs/files to the Rust server. Changes to the Markdown files show up after the next cargo run.

Pages are grouped in the sidebar by the section key in their front matter: Getting started, Running Stacklane, Reference or Project. Pages with a parent key appear under that page. nav_order sets the order.

Build a release binary#

The web interface is embedded in the binary at compile time, from ngx-ui/dist/portal/browser/. Build the frontend first:

make backend

The binary is target/release/stacklane.

If you build the backend without the frontend, the build still works, but the panel shows The web interface is not included in this build. instead of the portal. The API works normally.

Build the Debian package#

make deb

The package is written to dist/, for example dist/stacklane_0.1.0-1_amd64.deb. It is built for the architecture of the build machine. Build on an arm64 machine to get an arm64 package.

The package contains:

The package metadata is in Cargo.toml under [package.metadata.deb].

Contributing#

Contributions are licensed under the MIT License.