Nodara documentation · Updated 30 September 2026

A good place to start.

From private repository access to your first running panel. Install the panel, one worker and the Docker agent together on a single Debian VM.

See the live installation walkthrough → Follow real screenshots from sign-in to a running Minecraft server, file transfers, backups and repair.

1. Activate your repository access

1. After your purchase, use the private repository URL and access instructions supplied with your order. Accept the GitHub organization or repository invitation using the GitHub account you provided.
2. Open that URL while signed in and confirm you can see the code. A private-repository 404 usually means you are signed out, using another account, or have not yet accepted the invitation.
3. Obtain the reviewed commit or release specified for your installation. Repository access and a URL are both needed; the URL alone does not grant access.

This public website provides documentation, not an automated checkout or instant account provisioning. For a missing invitation, use the contact provided with your purchase; do not post payment details or access tokens publicly.

The installation/repair/update code was tested for v0.4.0-alpha.1 at ea2d761db92ac76a98ff9062082ed6123bf3b74f. Use the reviewed revision supplied for your order; if it differs, follow that revision’s release notes. Do not install an arbitrary moving branch.

2. Prepare a fresh VM

• Debian 13, systemd and Python 3.13, with administrator/root access and an IPv4 interface for game traffic.
• At least 2 GiB RAM for installation. This is not a Minecraft capacity recommendation. Reserve CPU and memory for the OS, panel, worker, agent and Docker, then budget additional resources and storage for games and backups.
• A clean machine: no existing Nodara accounts/directories, Docker installation/data, proxy configuration or certificate-management state. Ports 80, 443, 8000 and 8081 must be free; 2022 must also be free if enabling SFTP.
• A DNS hostname such as panel.example.com, resolving to the VM from both the VM and its users. Plan NAT/hairpin DNS if your VM is behind a router.
• Outbound access for Debian packages, Python dependencies and the private Git repository; game image and runtime downloads need connectivity too.

Keep the panel account separate from the Docker-capable agent account. The installer creates these accounts for you. Sharing one VM also shares its resources and failure boundary. For existing proxy servers or separate nodes, use the full manual deployment guide.

3. Plan DNS and network access

The installer does not change firewall or router rules. Check exposure from another machine, including Docker-published game ports; a generic host firewall rule alone may not filter them.

4. Choose Nginx, Apache or Caddy

Choose the server you know. Each option provides HTTPS in front of the same loopback panel.

Public HTTPS: have working public DNS and inbound validation connectivity ready. The installer asks you to accept public CA terms before issuance. Do not select this mode for a private-only hostname.

Existing CA: prepare absolute paths to a full-chain PEM certificate, its matching unencrypted private key and a single issuing root CA certificate. The certificate must cover your panel hostname, pass strict chain validation and remain valid for at least one day. Keep the key private. Install the CA on client devices too; never disable certificate verification.

Existing certificates are copied into the selected proxy’s directory. Replacing the original input files does not renew those copies. You must replace the installed certificate/key with protected ownership and reload the proxy before expiry.

5. Download your reviewed release

Run these commands on the fresh Debian VM. First install the bootstrap prerequisites:

sudo apt-get update
sudo apt-get install -y python3 git openssl iproute2 ca-certificates
python3 --version

Replace YOUR_PRIVATE_REPOSITORY_URL with the URL supplied to you and YOUR_REVIEWED_COMMIT with the full reviewed commit hash before running this block:

sudo git clone YOUR_PRIVATE_REPOSITORY_URL /usr/local/src/nodara
sudo git -C /usr/local/src/nodara checkout --detach YOUR_REVIEWED_COMMIT
cd /usr/local/src/nodara
sudo git status --short
sudo git rev-parse HEAD

Authenticate Git using an account with repository access. For HTTPS, use your GitHub username and a repository-scoped token when Git requests a password; do not embed the token in the URL or command. If using SSH, the root Git process must have its own authorized key and verified GitHub host entry. Authentication used by your normal shell is not automatically available to sudo git.

The checkout must be clean and root-owned. git status --short should print nothing; git rev-parse HEAD must match your chosen revision. Do not copy a Windows virtual environment, development database or local secrets onto the VM.

From /usr/local/src/nodara, start the interactive installer:

sudo python3 -m scripts.install_onprem

6. Answer the installer prompts

1. HTTPS proxy: choose nginx, apache or caddy.
2. Panel hostname and certificates: enter your DNS hostname, select public or existing, supply the contact email, and provide CA consent or PEM paths as appropriate.
3. Game networking: select an IPv4 address actually present on the VM. The player address can be your public/NAT address or DNS name; do not use a non-local NAT address as the bind IP.
4. Capacity: enter the memory and CPU available to games after reserving host capacity.
5. Optional SFTP: enable port 2022 only if you need it and have configured network access.
6. SMTP: supply the server, STARTTLS port, username, hidden password and sender email. If skipped, emails are stored locally; invitations and password resets will not be delivered.
7. Confirm: review the summary and type INSTALL. During installation, create your administrator through Django’s username/password prompts. There is no default administrator password. Save the username and password you choose; the Linux root login and GitHub token do not sign you in to the panel.

The installer installs locked dependencies, creates separate service accounts, initializes the database, registers a local node and starts the selected proxy, panel, one worker and Docker agent. It preserves generated credentials in root-only environment files, records a repair baseline after successful validation and installs the separate maintenance helper. Configure repository access using the update guide.

7. Verify your installation

sudo systemctl status nodara-panel nodara-worker nodara-agent
sudo nodara-repair check
sudo cat /etc/nodara/installation-complete

installation-complete is written only after successful installer checks. Open https://YOUR_PANEL_HOSTNAME/login/, verify the certificate and styles, sign in, enable MFA and save recovery codes securely. The local node is registered automatically; verify its connection in the panel.

1. Create a disposable test server. Personally review and accept the Minecraft EULA when prompted.
2. Wait for the worker to finish provisioning, check console readiness and connect a real game client.
3. Test graceful restart, world persistence, backup/restore and reboot recovery with test data.
4. Verify SMTP delivery, SFTP if enabled, certificate renewal and network exposure from another machine.
5. Back up and test restoring the panel, credentials, node state and game volumes before admitting users.

Verified in CI: fresh Debian 13 installations, HTTPS administrator login, synthetic worker/agent execution, installation fault recovery, rollback, preserved database/world sentinel/volumes, and reboot recovery passed for all three proxies on 30 September 2026 for the current release. Update and interrupted-update recovery checks also passed, including an Ubuntu 24 commissioned installation. Real Minecraft gameplay, public CA issuance/renewal and your network/storage remain site-specific acceptance checks. View the test run (repository access required).

8. Repair a damaged installation

Use the standalone command from the VM console or SSH, even if the panel is down. Inspect first, review the affected files and services, then approve restoration:

sudo nodara-repair check
sudo nodara-repair plan
sudo nodara-repair apply

apply requires REPAIR and restores the recorded source, units, environment files and Nodara HTTPS site. It preserves original secrets, validates configuration and checks service health. Intentional edits to managed files will also be replaced. Pending/running jobs and unsafe or unknown states block changes.

After an interrupted repair, use sudo nodara-repair recover and confirm RECOVER. It restores pre-repair state, which may still need attention. Later edits can block recovery. Do not delete the journal.

Auto-repair requires a healthy baseline from the fresh installer. It does not adopt older/manual installations, upgrade dependencies, repair game worlds, restore databases or renew certificates. Read the complete auto-repair and recovery reference before using it.

9. Backups, certificates and upgrades

For Nginx/Apache public certificates, test sudo certbot renew --dry-run and inspect sudo systemctl status certbot.timer. Caddy renews public certificates itself; monitor its logs and certificate expiry. Existing-CA certificates require your own renewal process.

Nodara’s code is exported to /opt/nodara, not installed there as a Git checkout. Do not run git pull there or rerun the fresh installer for upgrades. Supported single-VM installations can now check and approve private alpha releases from Updates. Configure read-only GitHub access once, disconnect SFTP clients, review the exact release and confirm with your panel password and configured MFA. The helper backs up local installation state and validates a replacement repair baseline. Game worlds require separate backups; schema rollback needs matching code and state. Older commissioned pilots use the separate bootstrap path in that guide.

10. Troubleshooting

sudo journalctl -u nodara-panel -u nodara-worker -u nodara-agent -n 100 --no-pager
# Run only the validator for your selected proxy:
sudo nginx -t
# Apache: sudo apache2ctl configtest
# Caddy: sudo caddy validate --config /etc/caddy/Caddyfile

Keep raw logs, passwords, tokens, private keys and recovery copies out of public reports. Use the full manual guide and configuration examples for separate-node deployment or interrupted installation recovery, preserving the single-VM paths where applicable.

What comes next

Phases 1, 2 and 3 are complete. Phase 4 is in progress: installation resilience and pilot validation are underway, with bot/application runtimes, Git deployment and hosted-application domain/rollback workflows on the roadmap. These broader Phase 4 capabilities are not all available yet.