From an empty server to a verified platform.

What Server5 does

Server5 turns infrastructure preparation into a controlled sequence rather than a collection of unrelated shell commands. One JSON configuration describes the intended edition, license holder, topology, network, host, virtualization, cluster and backup settings. The CLI validates that contract, inspects the target machine, explains required changes, applies approved actions and records evidence.

Editions and permitted use

A company must use Enterprise even when it runs Server5 on one Ubuntu host. Edition is determined by buyer and purpose, not merely server size.

Technical requirements

• Python 3.10 or later and administrative access.
• Ubuntu Server 24.04 LTS for the current Ubuntu target.
• Docker Engine and Docker Compose plugin for container workloads.
• Proxmox VE 8.x for Enterprise virtualization.
• K3s with embedded etcd for the Enterprise cluster target.
• Independent Proxmox backup storage or PBS for VM disaster recovery.
• Optional S3-compatible storage for etcd snapshots.

Supported architecture

Ubuntu + Docker

The direct-host path prepares one Ubuntu Server machine for Docker workloads, establishes project directories and validates the operating system, runtime, firewall and application endpoints.

Proxmox + K3s

The Enterprise path prepares a VM on Proxmox, bootstraps K3s, supports additional server or agent nodes and separates recovery into virtual-machine, etcd and application-data layers.

Server5 does not hide the underlying platforms. Reports identify actual component versions and preserve operational context for diagnosis and rebuilds.

Configuration contract

A single JSON document uses schema version 1. Unknown fields, incompatible edition/topology combinations, invalid networks and plaintext secrets are rejected.

{
  "schema_version": 1,
  "edition": "medium",
  "license_holder": { "type": "individual" },
  "topology": "ubuntu-docker",
  "host": { "admin_user": "serveradmin", "projects_dir": "/srv/projects" },
  "network": { "lan_cidr": "192.168.1.0/24" }
}

Start from the edition example included with Server5 and validate before resolving secrets or contacting a target host.

Recommended safe workflow

1. Copy the configuration example for the purchased edition.
2. Set host, network, storage and topology values.
3. Store secrets in environment variables or protected files.
4. Run validate.
5. Run read-only preflight and resolve blockers.
6. Review plan.
7. Run install --yes only on the intended target.
8. Run verify for every applicable target.
9. Perform and record recovery drills.
10. Generate and retain the final report and package checksum.

CLI reference

From the repository root use python product/server5.py. In a delivered Linux package use ./server5. Both expose the same commands.

python product/server5.py --version
python product/server5.py validate --config server5.json
python product/server5.py validate --config server5.json --resolve-secrets

python product/server5.py preflight --config server5.json --target auto
python product/server5.py preflight --config server5.json --json --output preflight.json

python product/server5.py plan --config server5.json --target auto
sudo ./server5 install --config server5.json --target auto --yes

sudo ./server5 verify --config server5.json --target ubuntu
sudo ./server5 verify --config server5.json --target k3s-server --json --output verify.json

./server5 recovery plan --config server5.json --layer application
sudo ./server5 recovery record --config server5.json --layer application \
  --result passed --started-at 2026-10-07T08:00:00Z \
  --ended-at 2026-10-07T08:30:00Z --backup-at 2026-10-07T07:45:00Z \
  --evidence /srv/evidence/restore.log
./server5 recovery status --config server5.json

sudo ./server5 report --config server5.json --target auto --output delivery/final
sudo ./server5 monitor --config server5.json --target auto --json
sudo ./server5 update plan --config server5.json --target auto --to-version 1.1.0

python product/server5.py release build --edition medium --output-dir dist
python product/server5.py release verify \
  --archive dist/server5-1.0.0-rc.1-medium.zip \
  --checksum dist/server5-1.0.0-rc.1-medium.zip.sha256

Execution targets

Enterprise evidence may require both Proxmox and K3s reports. One target does not replace another.

Secrets and sensitive data

{
  "token_ref": "file:/root/.server5/secrets/k3s-token",
  "access_key_ref": "env:SERVER5_S3_ACCESS_KEY"
}

• env:NAME resolves an environment variable.
• file:/absolute/path reads a protected file.
• Temporary adapter files use mode 0600 and are removed after success or failure.
• Journals and reports store references and statuses, not secret values.

Production-readiness verification

Verification checks resulting state rather than assuming a successful command means a healthy platform. Depending on target, it checks services, Docker, K3s node readiness, workloads, storage, backups, firewall, DNS, TLS and external health endpoints.

Accepted exceptions remain warnings and never convert a failed check into success. Offline mode records that external checks were skipped.

Backups and recovery

A backup is not treated as proven until a restoration drill is recorded.

• VM: Proxmox backup or PBS restores the machine.
• etcd: K3s snapshots restore control-plane state.
• Application: workload procedures restore persistent data.

Recovery records calculate observed RPO and RTO. Enterprise status requires current successful evidence for every configured layer.

Reports and evidence

The final delivery report is generated as JSON for automation and HTML for review. It combines configuration identity, inventory, preflight, verification, recovery status, component versions, accepted exceptions and outstanding risks.

Evidence from multiple machines can be imported. Imported documents are validated and secret-like values are removed.

Security model

• Validation precedes privileged actions.
• Plans are available without changing the host.
• Installation requires explicit --yes.
• Foreign Proxmox resources with conflicting IDs block execution.
• Idempotent checks skip correctly configured resources.
• Atomic journals exclude configuration bodies and credentials.
• Inactive firewalls, unhealthy nodes and missing recovery evidence block readiness.
• Checksums and manifests detect altered archives.

Release and delivery

Medium and Enterprise packages are built separately. Medium excludes Proxmox/K3s content; Enterprise contains the complete topology. File order, timestamps and permissions are normalized so identical sources produce identical bytes.

Every archive includes RELEASE-MANIFEST.json and an external SHA-256. A delivered archive must never be silently replaced under the same version.

Troubleshooting

Scope, responsibilities and support

A Server5 license covers the delivered software version and documentation. Unless separately agreed, it does not include installation services, continuous operation, monitoring, maintenance, incident response, future upgrades, hosting or hardware.

The holder remains responsible for access, backups, change windows, application data, compliance and testing before critical changes. Questions may be sent to support@server5.org.