Modula Deploy
Self-hosted platform for deploying apps and databases on your own servers.
Push to GitHub or pick an image, and Modula builds, deploys, routes and secures
it. The workflow is modeled on Railway's: a project canvas, environments, staged
changes, variables with references, domains, database backups and a CLI.
Status: alpha. It runs real apps, but expect rough edges and breaking
changes before 1.0. Today an instance has a single owner account; teams and
invites come later. Read SECURITY.md before exposing it.
Features
- Deploy from GitHub (auto-deploy on push, watch paths), a Docker image, or
modula up from a local directory. Builds use Railpack
or your Dockerfile, in a sandboxed BuildKit per workspace.
- Project canvas with environments, pending changes you review and deploy
together, health checks, pre-deploy commands, draining, rollback (rebuilds the
old commit) and live logs and metrics.
- Variables: per-service and shared, references (
${{ Postgres.DATABASE_URL }}),
sealed values, encrypted at rest with keys per environment.
- Databases: Postgres, MySQL, Redis, MongoDB templates with volumes, private
networking, TCP proxies, a Database tab (tables, rows, SQL, stats) and
encrypted backups to S3, R2, B2 or MinIO.
- Domains: generated domains and custom domains with automatic TLS (Caddy),
optional Cloudflare DNS.
- Servers: add more servers with one command or create them on Hetzner from
the dashboard; services are placed by load and location.
- Security: 2FA (TOTP), sudo mode for destructive actions, scoped API tokens,
per-route authorization, an audit log. See guide/security.md.
- CLI and config as code:
modula mirrors the Railway CLI's commands;
.modula/modula.ts (TypeScript, like Railway's railway.ts) or
.modula/modula.toml keeps a whole project in git.
Install
On a fresh Ubuntu 22.04+ or Debian 12+ server (2 GB RAM or more):
curl -fsSL https://usemodula.org/install.sh | bash
No domain is needed to start: the dashboard comes up on https://<server IP>
and you can set a domain later in Settings → Domain. The installer sets up
Postgres, Redis, Docker and Caddy, downloads binaries verified against a signed
checksum list, writes hardened systemd units, and prints a one-time setup token.
It also writes /root/modula-recovery-kit.txt with the master key: copy it
somewhere safe and delete it from the server.
Full details, including unattended installs, ports, upgrades and recovery:
guide/install.md.
Use
- Open the dashboard at the address the installer prints and paste the setup
token to create your admin account. Turn on 2FA under Account → Security
(security).
- Create a project and add a service from a GitHub repo, a Docker image, or a
database template (projects and services,
databases). Click Connect GitHub (in
Workspace Settings → Integrations) for deploys on push (integrations).
- Set variables, review the pending changes and deploy
(variables, deployments).
- Give it a domain (domains) and add more servers when you
need them (servers).
Or work from the terminal. Install the CLI on your own machine (Linux or macOS):
curl -fsSL https://usemodula.org/install-cli.sh | bash
Then log in and deploy the current directory:
modula login deploy.example.com # approve the login in your browser
modula init # create a project, or `modula link` an existing one
modula up # build and deploy this directory
modula logs # follow the logs
Every command is in guide/cli.md; scripting and agent use is in
guide/cli-for-humans-and-agents.md.
Documentation
The guide covers everything: projects and services,
variables, deployments, databases, backups, domains, servers, the CLI, the API,
and migrating from Railway.
Layout
crates/server modula-server: axum API, auth, authz, jobs, migrations, embedded UI,
internal CA, node endpoint (gRPC), deployments
crates/node modula-node: runs on every server; Docker runtime, Caddy, builds, databases
crates/cli the `modula` CLI
crates/crypto envelope encryption (XChaCha20-Poly1305, AAD-bound), tokens, argon2id
crates/proto modula.node.v1 gRPC protocol between server and node
crates/backup backup streaming, age encryption, outbound network guard
crates/hetzner Hetzner Cloud API client
web/ React SPA (served by modula-server)
deploy/ install.sh, release public key, e2e installer test
scripts/ check.sh (what CI runs), release.sh, dev-*.sh
guide/ user documentation
Develop
Prerequisites and conventions are in CONTRIBUTING.md.
scripts/dev-services.sh # Postgres :55432, Redis :56379 (127.0.0.1 only)
cp .env.example .env && set -a && . ./.env && set +a
(cd web && pnpm install && pnpm build) # without web/dist the UI is blank
cargo run -p modula-server -- keygen --out ./dev-master.key
cargo run -p modula-server # prints the one-time setup token
scripts/check.sh # fmt, clippy, tests, deny, audit, no-shell
Run a server (node) against it. The join command comes from Servers → Add
server or POST /api/nodes/join-tokens:
MODULA_JOIN_TOKEN=mcj_… cargo run -p modula-node -- --data-dir .dev/node join --server https://localhost:7101 --ca sha256:…
cargo run -p modula-node -- --data-dir .dev/node run
cargo test -p modula-node --test docker -- --ignored # real Docker round trip
On macOS, Docker Desktop can't route to container IPs from the host, so health
checks only pass when modula-node runs on Linux. scripts/dev-node.sh starts a
simulated server (a privileged container with its own dockerd, Caddy and node)
joined to scripts/dev-server.sh:
scripts/dev-node.sh dev-node-1 8080 # apps on http://<generated>.localhost:8080
scripts/dev-node.sh dev-node-1 --rm # remove it
For the UI with hot reload: scripts/dev-server.sh, then cd web && pnpm dev
(start the server with MODULA_PUBLIC_URL=http://localhost:5173).
Releases are built and signed with scripts/release.sh; the signing key lives
outside the repository and its public half is deploy/release.pub.pem.
deploy/e2e/run.sh runs the installer end to end in systemd containers.
Contributing
Contributions are welcome: bug reports, fixes, docs, and features.
- Found a bug or want a feature? Open an
issue with the
templates provided. For anything larger than a small fix, open an issue first so
we can agree on the approach.
- Want to send code? Fork the repo, set it up with the steps in
Develop, make your change on a branch, and run
scripts/check.sh
(the same checks as CI) before opening a pull request. Add tests for behavior you
change, and update the guide when users would notice.
- Docs help too. Fixes and clearer examples in
guide/
are some of the most useful contributions.
CONTRIBUTING.md has prerequisites, conventions and the review
process. Security issues go through SECURITY.md, never public
issues. Everyone taking part follows the Code of Conduct.
Security
Please report vulnerabilities privately, as described in SECURITY.md.
The design in brief:
- Every route declares its access policy; resource routes resolve the resource's
workspace and check your role before the handler runs. Non-members get 404.
- Mutations require an exact
Origin match (CSRF); sessions are hashed,
__Host- HttpOnly cookies, rotated on login and sudo.
- Secrets are sealed with keys per environment and AAD bound to their row;
revealing a variable needs sudo and is audited.
- Servers enroll with a CSR and a single-use join token over mTLS pinned to the
instance's own CA; revoked servers can't reconnect.
- Containers drop capabilities, run with
no-new-privileges, default memory and
CPU limits, one network per environment, and no access to cloud metadata.
Builds run in a sandboxed BuildKit per workspace.
- No shell strings anywhere (
scripts/no-shell.sh enforces it in CI).
License
AGPL-3.0-only. Third-party components and their licenses are listed in
THIRD_PARTY_NOTICES.md.
Modula Deploy is not affiliated with or endorsed by Railway Corp. "Railway" is
their trademark and is used here only to describe compatibility.
