Current stable release:
v0.7.0. See ROADMAP.md for next version planning.
A safety-first Linux web and application hosting control plane with cPanel migration tooling.
StePanel is an open-source server management panel written in Go. It installs Caddy by default, with Apache and OpenLiteSpeed available explicitly, plus PHP and a selectable MySQL, MariaDB, or PostgreSQL version. It provides a focused operations dashboard and imports cPanel cpmove backups through an asynchronous, validated workflow.
It is designed for people who want a small, understandable hosting control plane instead of a large opaque platform.
 Each site has its own workspace: domains, runtime, deployments, databases, backups, logs, workers, and tasks. |
 Recovery status says what has actually been proven: signed backups, restore rehearsals, and recovery point. |
 Customers sign in with MFA and see only their assigned sites, plan, and usage. |
 Every backup, restore, and site change runs as a durable job you can follow. |
The preview images use StePanel's dark appearance and CyberDuctTape demo
branding. These are screenshots of the real UI, captured with synthetic data by
scripts/capture-screenshots.sh. See
SCREENSHOTS.md for every view and how they are produced.
- Migration-focused: move cPanel accounts into a controlled Linux hosting environment.
- Safety-first: validate archives, reject unsafe entries, stage uploads privately, and expose restore status as a job.
- Small footprint: a Go control plane with a limited dependency surface.
- Operator-friendly: clear health endpoints, tamper-evident audit events, systemd deployment, and readable documentation.
- Flexible database layer: choose MySQL, MariaDB, or PostgreSQL and request an exact repository/AppStream version during installation.
- Database administration: optionally install phpMyAdmin for MySQL/MariaDB or phpPgAdmin for PostgreSQL; the dashboard reports service health and links to the matching administrator.
| Area | Included today |
|---|---|
| Installation | Caddy by default, or Apache/OpenLiteSpeed, PHP, MySQL/MariaDB/PostgreSQL, optional phpMyAdmin/phpPgAdmin, Exim/Dovecot/SpamAssassin/vsftpd, systemd, Debian/Ubuntu and RHEL-family systems |
| Migration | cPanel .tar.gz inspection, safe staging, website, SQL, staged mailbox restore, and fail-closed .htaccess conversion for Caddy |
| Operations | Dashboard, health endpoint, metrics endpoint, audit log, asynchronous restore jobs |
| Control plane | Durable SQLite state, independently supervised worker, leases/retries/cancellation, dead-letter readiness gate, desired-state reconciliation, and recovery inventory |
| Security | bcrypt credentials, signed sessions, CSRF protection, archive traversal checks, restricted service user, API token scopes, cross-tenant authorization boundaries, privilege escalation prevention, adversarial test coverage |
| Production Readiness | Startup validation of filesystem quotas, encryption keys, TLS configuration; diagnostic endpoint for production prerequisites; comprehensive security test matrix |
| Delivery | Dockerfile, ARM64/AMD64 release workflow, checksums, CI, vulnerability scanning |
The supported-by-evidence Operator Beta combinations and certification limits are listed in the installation platform matrix.
For cloud inventory/actions, DNS adapters, SSH inventory, WAF capability constraints, off-site backups, and operational configuration, see the integration guide, installation guide, operations runbook, customer workflows, and version compatibility and rollback.
Status: StePanel supports single-host operation with tenant-scoped account provisioning (TOTP MFA, assigned-site limits, plan-limited site creation by tenant owners, delegated roles, scoped access, resource profiles, and a customer plan/usage panel). Tenants are separated in the control plane and by Unix user and cgroup on the host, but sites share one kernel and network, so StePanel is not a security boundary between hostile customers; see what tenant isolation covers. Multi-tenant production deployment is NOT RECOMMENDED yet: provider-wide audit segregation, HA datastore/failover, and cross-host durable job routing remain open platform requirements. See PRODUCTION_READINESS.md for detailed capability status. Administrators can inspect verified local restore dependencies through the authenticated
/api/capabilitiesendpoint; remote backup access and each artifact's integrity are checked when an operation runs. Always run behind authenticated HTTPS and test restores against a disposable server before using production data.
Browser / API client
│ authenticated HTTPS
▼
Go control plane ── durable jobs, audit chain, desired state
│ narrow typed helper calls
▼
Root-owned platform helpers ── Caddy/Apache, PHP-FPM, databases, systemd
│ isolated site identities and cgroup profiles
▼
Web applications, databases, verified backups, recoverable releases
See SCREENSHOTS.md for every dashboard view, captured from the real UI with synthetic data.
Operational key backup and rotation procedures are documented in
docs/SECRETS.md.
Requirements: Go 1.26+.
git clone https://github.com/cyberducttape/StePanel.git
cd StePanel
make check
go run ./cmd/stepanelOpen http://localhost:8080. Local development uses data/imports and data/www, so root access is not required.
The container packages the control plane only. It does not run Apache, PHP, or a database server inside the container. Database administrator packages are host integrations and are not installed in the container image. Treat Docker and Kubernetes as control-plane packaging for evaluation or limited integration mode: they are not highly available and cannot provide the native host-management surface. Use the systemd installation for full single-host hosting. The production readiness report detects a Docker, Podman or Kubernetes runtime and flags it with a Deployment Mode warning.
docker build -t stepanel:local .
ADMIN_TOTP_SECRET="$(openssl rand 20 | base32 | tr -d '=\n')"
printf 'Save and enroll this administrator TOTP secret before continuing: %s\n' "$ADMIN_TOTP_SECRET"
docker run --rm -p 127.0.0.1:8080:8080 \
-e STEPANEL_TLS_TERMINATED=1 \
-e STEPANEL_ADMIN_PASSWORD='use-a-password-manager' \
-e STEPANEL_SESSION_SECRET="$(openssl rand -hex 32)" \
-e STEPANEL_AUDIT_KEY="$(openssl rand -hex 32)" \
-e STEPANEL_ADMIN_TOTP_SECRET="$ADMIN_TOTP_SECRET" \
-e STEPANEL_ACCOUNT_KEY="$(openssl rand -hex 32)" \
-e STEPANEL_ENVIRONMENT_KEY="$(openssl rand -hex 32)" \
-e STEPANEL_BACKUP_SIGNING_KEY="$(openssl rand -hex 32)" \
-e STEPANEL_BACKUP_ENCRYPTION_KEY="$(openssl rand -hex 32)" \
-e STEPANEL_REQUIRE_OFFSITE_BACKUP=1 \
-e STEPANEL_OFFSITE_TARGET='s3:bucket/stepanel' \
-e STEPANEL_SKIP_QUOTA_CHECK=1 \
-e RCLONE_CONFIG=/run/secrets/rclone.conf \
-v "$PWD/rclone.conf:/run/secrets/rclone.conf:ro" \
stepanel:localThe image can run with production safety settings and requires TOTP, an account key, an
environment key, a backup signing key (each at least 32 machine-generated
characters), a backup encryption key, and a working offsite rclone target. The
Docker example sets STEPANEL_SKIP_QUOTA_CHECK=1 because ordinary container
filesystems do not provide the native /var/www user-quota contract; this is
evaluation/integration mode, not a substitute for the native production
installer. The generated keys above are
for a throwaway trial: for a real installation generate them once, store them in
your secret manager, and back them up, because encrypted environment state and
signed backups cannot be read without them. This local example binds the
published port to host loopback. STEPANEL_TLS_TERMINATED=1 means the container
must be reachable only through a trusted HTTPS reverse proxy. For production
reverse-proxy deployments, use a private container network or explicit firewall
policy and configure STEPANEL_TRUSTED_PROXY_CIDRS for the proxy's actual
addresses; never publish the HTTP port directly to an untrusted network. Mount
provider credentials through your secret manager; do not bake them into the
image.
Use a tagged release artifact for production installation. The archive
contains the binary, installer, helpers, service files, and web assets needed
by install.sh:
release=v0.7.0
arch=amd64 # use arm64 on aarch64 hosts
curl -fsSLO "https://github.com/cyberducttape/StePanel/releases/download/${release}/stepanel_${release#v}_linux_${arch}.tar.gz"
curl -fsSLO "https://github.com/cyberducttape/StePanel/releases/download/${release}/SHA256SUMS"
grep "stepanel_${release#v}_linux_${arch}.tar.gz" SHA256SUMS | sha256sum -c -
tar -xzf "stepanel_${release#v}_linux_${arch}.tar.gz"
# Continue with the environment-variable installation command in
# docs/INSTALLATION.md#build-and-install.The v0.7.0 installer takes its settings from environment variables; use the
complete release installation example
for the required keys, offsite target, and rclone configuration. The guided
installer is available from main and is documented separately; do not pass
--guided to the v0.7.0 release installer. Before starting, install rclone
and add a storage remote with sudo rclone config; the installer tests that
remote before continuing.
The installer records the selected database engine/version, creates a restricted stepanel service account, writes the requested panel hostname into the selected webserver, and binds the control plane to 127.0.0.1:8090. Caddy provisions HTTPS automatically; Apache installations must complete TLS termination before signing in.
Production installation requires a working offsite target. Set RCLONE_CONFIG
to an absolute path readable by the stepanel service account before running
the installer, for example with sudo env RCLONE_CONFIG=/etc/stepanel/rclone.conf ./install.sh. The installer preserves this explicitly supported child-process
setting in /etc/ste-panel.env, and its post-install readiness probe verifies
that the configured target can write, read, and delete a health object.
Safety-invariant bypasses (STEPANEL_SKIP_QUOTA_CHECK,
STEPANEL_SKIP_STARTUP_DB_RECONCILE, STEPANEL_SKIP_STARTUP_HOST_RECONCILE,
STEPANEL_LAB_HTTP_COOKIES, STEPANEL_LAB_DIRECT_ROOT_BROKER) exist only for
disposable lab hosts. The installer refuses to run while any of them is set in
the environment or in an existing /etc/ste-panel.env, unless you pass
./install.sh --unsafe-lab, which also records STEPANEL_UNSAFE_LAB=1. A
production panel refuses to start with a bypass but without that marker; with
it, startup logs a critical warning, writes a
control_plane.safety_bypass_active audit event, and
/api/admin/production-readiness reports a critical failure.
Nightly/manual installation smoke CI exercises real disposable systemd hosts for AlmaLinux, Rocky Linux, Ubuntu, and Debian, including package installation, service restart, synthetic site creation, and selected-webserver validation.
Verify release provenance and the GitHub attestation before installing on a production host. The checksum authenticates download integrity; the release page's SBOM and build-provenance attestation provide the corresponding supply chain evidence. Building from source is a developer/contributor workflow: see Local development and keep it separate from the normal operator installation path.
After installation, inspect the running binary and build provenance with:
/opt/stepanel/stepanel versionRun stepanel dr-check on a host to emit a secret-safe control-plane disaster
recovery manifest. It inventories state files, keys, Git trust material,
external rclone dependencies, site data, and regeneration-only helpers without
copying secret values. Use stepanel backup-control-plane DEST to create a
verified SQLite backup, and stepanel restore-control-plane SOURCE --dry-run
to validate a candidate before the guarded maintenance-window restore:
stepanel restore-control-plane SOURCE --replace.
For API automation, build or install stepanelctl and set STEPANEL_URL and
STEPANEL_TOKEN. The read-only operator CLI emits the API's JSON directly:
stepanelctl doctor --production
stepanelctl sites list
stepanelctl site inspect example
stepanelctl jobs list
stepanelctl jobs watch site-create-<id>doctor --production checks the production prerequisite report, while
jobs watch polls durable job state until it reaches a terminal result.
- Migrate a cPanel account with the cpmove guide.
- Restore a WordPress
.wpressarchive with the WordPress guide. - Deploy and roll back a site through Git releases.
- Run the disposable lab before touching production data.
Read these to understand what StePanel is, does, and can do:
- docs/FEATURES.md — Authoritative capability matrix and feature status
- docs/SECURITY.md — Threat model, security boundaries, known limitations
- docs/ROADMAP.md — Medium-term direction and planned work
- docs/CURRENT_STATUS.md — Where each 1.0 release gate stands today
- docs/V1_PRODUCTION_GATES.md — Authoritative 1.0 release gates
- docs/INSTALLATION.md — Installation, configuration, production setup
- docs/OPERATIONS.md — Running and managing StePanel
- docs/SECRETS.md — Backup, rotation, and disaster recovery procedures
- docs/TROUBLESHOOTING.md — Diagnosing failed jobs, services, and installs
- docs/CPMOVE_IMPORTS.md — Migrate from cPanel
- docs/WPRESS_IMPORTS.md — Restore WordPress
.wpressarchives - docs/ARCHIVE_IMPORTER.md — Import sites from other hosting providers
- docs/GIT_DEPLOYMENTS.md — Deploy and roll back via Git
- docs/CUSTOMER_WORKFLOWS.md — Multi-tenant operations and workflows
- docs/SHARED_HOSTING.md — Customer accounts, plans, and the shared-hosting beta boundary
- docs/ARCHITECTURE.md — System design and components
- docs/CODE_ORGANIZATION.md — Where code lives: root package,
internal/packages, binaries - docs/adr/ — Architecture Decision Records (immutable design history)
- docs/THREAT_MODEL.md — Detailed threat analysis and mitigations
- docs/API_GUIDE.md — API authentication, permissions, copyable workflows
- docs/openapi.yaml — Machine-readable OpenAPI contract
- docs/DEVELOPER_WORKFLOWS.md — Contributor guide and local development
- docs/lab-results/2026-10-09-rocky9-kvm-certification.md — Full recovery matrix, abrupt guest loss, and ENOSPC on a SELinux-enforcing KVM guest
- docs/REAL_HOST_FAILURE_MATRIX.md — Which failure scenarios have real-host evidence
- docs/lab-results/ — All dated recovery and certification results
- docs/CASE_STUDY.md — Real-world backup and recovery example
- docs/INTEGRATIONS.md — Cloud provider, DNS, and third-party integrations
- docs/RELEASING.md — Release process and artifact generation
- docs/INCIDENT_LAB.md — Incident response procedures and drills
- CHANGELOG.md — Version history and release notes
- docs/DOCUMENTATION_GUIDE.md — How documentation is organized and maintained
- CONTRIBUTING.md — Contribution guidelines
- observability/README.md — Metrics, logging, and monitoring
- Release artifacts — Binary releases, checksums, SBOM
The API guide explains authentication, permissions,
copyable curl workflows, asynchronous jobs, backups, migrations, databases,
and customer scope. Use the versioned OpenAPI contract as
the machine-readable endpoint, schema, response, and authorization reference.
Configuration is intentionally documented in the installation guide and secrets/DR guide, rather than duplicated on the landing page. Those references include the complete environment-variable table, production validation rules, key backup and rotation procedures.
Invalid numeric limits and unsafe production paths are rejected at startup instead of silently falling back to defaults. Production state paths must be absolute so service behavior does not depend on its working directory.
Set STEPANEL_INSTALL_MAIL=1 during installation to install Exim, Dovecot,
and SpamAssassin.
Set STEPANEL_INSTALL_FTP=1 to install and enable vsftpd. The panel reports
vsftpd in the service inventory. Local users are chrooted to their site root
and passive ports default to 40100-40200; configure FTPS and create
least-privilege site users before allowing external access. Plain FTP should
only be used on a trusted management network.
Set STEPANEL_INSTALL_NODE=1 STEPANEL_NODE_VERSIONS=20.18.0,22.14.0 to install
Node versions through NVM. The panel can select an installed version per site
and generate a validated reverse proxy for a local app backend in the selected
webserver.
Managed apps are supervised by per-site systemd units and can be started,
stopped, or restarted through the authenticated API.
Set STEPANEL_INSTALL_SECURITY=1 to install ClamAV, inotify-based PHP
monitoring, and recoverable quarantine handling. This is a defense-in-depth
layer, not a guarantee against all malware; keep applications patched and use
least-privilege service accounts.
Mailbox contents are preserved in the private mail root and reported by the
restore job; activation still requires destination domain, mailbox, DNS, TLS,
and credential mapping.
The road to 1.0 is about evidence, not new features: repeated real-host failure-recovery runs, upgrade and rollback tooling, a stable API policy, and a security review. CURRENT_STATUS.md tracks where each release gate stands; see the roadmap for the full plan.
StePanel is released under the MIT License.