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#
| Tool | Version | Used for |
|---|---|---|
| Rust | 1.88 or newer (edition 2024) | The backend |
| Node.js | 22 or newer, with npm | The frontend |
| GNU Make | any | The build targets |
cargo-deb | any | Building 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#
| Target | What it does |
|---|---|
make or make all | Same as make deb. |
make frontend | Installs the npm packages with npm ci and builds the portal into ngx-ui/dist/. |
make backend | Builds the frontend, then builds the stacklane binary in release mode. |
make deb | Builds the frontend, then builds the binary and the .deb package into dist/. |
make dev | Starts the Angular development server for the portal on port 4200. |
make test | Runs all Rust tests and the portal tests. |
make lint | Checks the Rust formatting and runs Clippy with warnings as errors. |
make clean | Removes the Rust build output, ngx-ui/dist and dist. |
make site | Builds the website in site/ into one binary at site/target/release/stacklane-site. |
make site-dev | Starts 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.
-
Install the frontend packages:
cd ngx-ui && npm ci && cd .. -
Create a configuration file
dev.tomlin 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 = trueRelative paths are relative to the directory you run the command in.
public_urlpoints at the development server, because that is the address in your browser. The session refresh checks theOriginheader against it. -
Create the secret key and the owner account:
cargo run -- -c dev.toml keygen cargo run -- -c dev.toml setup -
Start the backend:
cargo run -- -c dev.toml serve -
In a second terminal, start the frontend:
make dev -
Open
http://localhost:4200and 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:
- Rust formatting uses
rustfmtwith a maximum line width of 120. - Clippy warnings fail the build.
unsafecode is forbidden.- The frontend uses Prettier.
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.
| Path | Contents |
|---|---|
src/main.rs | The stacklane binary and its command line |
src/config.rs, crypto.rs, jwt.rs, model.rs, password.rs, validate.rs, vat.rs | Configuration, domain types, validation, VAT rules, password hashing, cryptography, JWT |
src/store | SQLite persistence |
src/api | HTTP API, authentication, rate limits, audit log, email and the embedded web interface |
src/cloud | Proxmox VE client and the instance task worker |
src/hosting | cPanel/WHM, DirectAdmin and Pterodactyl clients, game server management, Minecraft catalog and the provisioning worker |
src/domains | Registrar clients, PowerDNS and the registration and renewal worker |
src/billing | Payment gateways, VIES checks, usage metering, invoicing and dunning |
src/import | WHMCS import |
migrations | Database migrations, embedded in the binary |
tests | End-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/.
| Project | Path | Contents |
|---|---|---|
ui | ngx-ui/projects/ui | The @stacklane/ui component library and design tokens |
portal | ngx-ui/projects/portal | The 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#
| Path | Contents |
|---|---|
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
| Variable | Default | Description |
|---|---|---|
STACKLANE_SITE_LISTEN | 127.0.0.1:8081 | Address the server binds to. |
STACKLANE_SITE_URL | http:// plus the listen address | Public address, used for canonical links and the sitemap. |
STACKLANE_SITE_LOG | info,tower_http=warn | Log 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:
/usr/bin/stacklane/etc/stacklane/stacklane.toml, frompackaging/stacklane.toml- the systemd unit from
packaging/debian/stacklane.service - the maintainer scripts
preinst,postinstandpostrmfrompackaging/debian/ /usr/share/doc/stacklane/README.md
The package metadata is in Cargo.toml under [package.metadata.deb].
Contributing#
- Open an issue before you start a larger change.
- Every pull request must pass
make lintandmake test. - Database changes go into a new migration in
migrations/. Never edit a released migration. - New API behavior needs an end-to-end test in
tests/. - Changes to authentication, sessions, permissions, cryptography or customer data need a second reviewer.
- Write commit subjects in the imperative, under 72 characters.
Contributions are licensed under the MIT License.