Skip to main content

Documentation center

Installation and operations.

Install Amanah Sport, manage services, and recover data on your venue's VPS.

Updated 19 November 2026 Ubuntu 24.04 amd64 Created by Amanah Karya Perdana

Save guide (.md)

How This Guide Applies to Your License Plan

Mandiri Plan (Rp7.9M)

100% self-installed by your venue IT team following Sections 1-3 + 1 online orientation session (60 mins).

Plus & Multi-Branch Plans

Sections 1-3 are handled end-to-end by our team until live; Sections 4-13 serve as your daily operations manual.

VPS Ops (Rp200k/mo) vs Software Care (Rp3.6M/yr)

VPS Ops covers server health monitoring & weekly backups (Sections 4-6 & 10); Software Care delivers Year 2+ feature upgrades (Section 12).

Public installer not yet available

The guide is ready to read. Begin installation after the Amanah team supplies the official installer, checksum, and license key.

1. Prerequisites

Use an Ubuntu 24.04 LTS VPS with amd64/x86_64 architecture, with root access or a sudo -i session. Customer images currently target linux/amd64; ARM servers are outside this installation path.

Prepare the following:

  • A booking domain or subdomain owned by your venue, such as booking.venue.example. Your booking domain is separate from Amanah's licensing domain.
  • An A record pointing to the VPS public IP. If you publish an AAAA record, its IPv6 address must also point to the correct server and serve the application.
  • Inbound TCP ports 80/443 for Caddy and HTTPS, plus operator SSH access. PostgreSQL, backend, frontend, and WAHA do not need public ports.
  • Outbound access to the image registry, certificate service, licensing service, and the providers you use: payments, WhatsApp, Telegram, email, or AI.
  • The owner's email, a unique admin password (at least 12 characters, at most 128 UTF-8 bytes), venue name, and official license key. Keep secrets in a password manager.
  • CPU, RAM, and disk sized to your Jakarta cloud server workload tier:
  • 1 Location (Web Chat & Telegram only): minimum 2 vCPU / 2-4 GB RAM / 40-60 GB SSD NVMe.
  • 1 Full Location (Web + WhatsApp + AI Assistant + daily backups): recommended 2-4 vCPU / 4-8 GB RAM / 60-100 GB SSD NVMe.
  • Multi-Branch (2-5+ branches on 1 unified central server & primary domain): recommended 4-8 vCPU / 8-16 GB RAM / 100-160 GB SSD NVMe.

An unlimited court allowance in your software license does not mean unlimited VPS memory or storage.

  • An encrypted backup destination outside the VPS and an agreed downtime window for consistent backups.

Official releases use public images pinned by digest. The installer pulls them without a GitHub account or docker login; application operations still require a valid license.

You do not need application source code or a compiler. On a fresh Ubuntu 24.04 server, the installer prepares Python, system certificates, Docker Engine, and Compose v2 from official repositories when missing. It does not automatically remove conflicting Docker packages; an operator must resolve those first. Allow at least 10 GiB of free disk space for initial installation; production capacity depends on your workload. Python 3.10+ is required when running release.py directly.

2. Receive and run the single installer file

The executable in these examples is named amanah-installer. Use the filename and checksum supplied with your actual release. Verify its SHA-256 against the value received through the official handover channel before running it as root:

Terminal
sha256sum /root/amanah-installer

Once the checksum matches, install the executable somewhere convenient for future use:

Terminal
install -m 0755 /root/amanah-installer /usr/local/bin/amanah-installer
amanah-installer install --directory /opt/amanah-sport

Follow the installer prompts. When asked for a domain, enter a hostname without https://, a port, or a path. Enter passwords and the license key through the provided prompts; keep them out of command arguments, screenshots, and support tickets.

The wizard also offers optional integrations. Choose only providers that the venue will use:

ChoiceCollected during installationRemaining onboarding
WhatsAppEnable the local messaging servicePair the phone in admin and test send/receive
Google loginOAuth client ID and secretRegister the origin and https://booking.venue.example/api/auth/google/callback with Google, then test login
TelegramOptional numeric bot ID for loginConnect the bot/session in admin and authorize the login domain with the provider
PaymentsManual, Midtrans, or XenditEnter credentials and sandbox/production mode in branch settings; test a payment and its callback
EmailNone, SMTP, Resend, or SendGrid; verified sender and applicable credentialsVerify sender DNS and test delivery through the application

Skipping an integration leaves it for later configuration. Selecting a provider does not send a test message or payment automatically. AI and Web Push remain part of the admin onboarding checklist.

The installer checks the signed release manifest, product identity, platform, manifest expiry, ZIP checksum and size, and customer release marker before running the package. The planned official manifest location is https://download.amanahsport.cloud/releases/stable.jws. A successful download does not make a package safe to run if signature verification fails.

Reserving a license key binds the installation and grants setup access; reservation does not start the trial. The 30-day period starts at activation after installation readiness checks pass. Record the start and end time actually returned by the licensing service. If the activation response is interrupted, a retry retrieves the same period instead of extending it.

If your terminal or SSH session disconnects during a resumable stage:

Terminal
amanah-installer resume --directory /opt/amanah-sport

If database initialization finished before the journal was saved, resume checks the completion marker, migrations, and installation identity before continuing; it does not initialize the data again.

If the saved manifest expires, resume retrieves a fresh official manifest and only continues with the identical package: version, hash, size, platform, and contract must match. A different package does not authorize replacing an existing installation. Use an official installer that meets the release minimum version; never edit the journal or disable signature verification.

Do not run a fresh installation over a directory containing data to recover an interrupted process. If .release-initialize.pending exists, follow section 9: partially completed database initialization differs from an unfinished download or service startup.

3. From application startup to a ready venue

HTTPS and health checks confirm that the application responds. Before accepting customers, configure the venue's business settings and verify its integrations.

  1. Open the booking domain over HTTPS and sign in as the owner. Verify admin access, not just the login page.
  2. Confirm that sample branches and courts are gone. Set locations, time zones, courts, prices, business hours, holidays, peak rates, and extras to match your venue.
  3. Configure taxes, bank/QRIS details, payment deadlines, cancellation/refund policies, FAQs, referrals, logo, contact details, and branding. Review default content before showing it to customers.
  4. Connect the venue's payment gateway and configure the correct callback domain. Test a payment and its callback; a visible QRIS option does not prove that settlement updates work.
  5. Connect WhatsApp in the admin interface and verify the phone session and callback. A healthy WAHA container does not mean the phone is paired. Session capacity must match the WAHA edition that was tested.
  6. Configure Telegram, AI, email, OAuth, and Web Push only when used. EMAIL_PROVIDER=none means email is disabled. PWA and Web Push require HTTPS and compatible devices and permissions.
  7. Create staff accounts with the appropriate branch scope and permissions; confirm that access to other branches is denied.
  8. Test bookings, payments, invoices, cancellations, vouchers, chat, and notifications with approved test data and recipients. Record the results and image versions.

The owner signs in with email/password at /admin/login, including before a WhatsApp number has been paired. The member login page also provides an owner/staff sign-in link.

The installed PWA name follows APP_NAME, populated from the wizard venue name, so the same frontend image can serve different venue brands without rebuilding. Operators may configure PWA_NAME, PWA_SHORT_NAME, PWA_DESCRIPTION, PWA_THEME_COLOR, PWA_BACKGROUND_COLOR, and local PNG icon paths PWA_ICON_192/PWA_ICON_512 at runtime. The 192/512 pixel icons must already exist in the image assets; external URLs are unsupported. After applying configuration, the manifest updates without caching and keeps the same application identity. Browsers may delay label/icon updates on existing shortcuts. Website appearance remains configurable in the admin interface.

After login and readiness are verified, the installer clears bootstrap credentials from its configuration and journal. For a manual helper installation, clear both ADMIN_EMAIL and ADMIN_PASSWORD in .env using a private editor, then apply the change with up. Changing bootstrap values does not reset an existing account password. Never print .env into terminal captures or support logs.

4. Daily commands

These examples use /opt/amanah-sport. Substitute the actual installation directory when different.

TaskCommand
View application statusamanah-installer status --directory /opt/amanah-sport
Run diagnosticsamanah-installer doctor --directory /opt/amanah-sport
Start application servicesamanah-installer start --directory /opt/amanah-sport
Stop application servicesamanah-installer stop --directory /opt/amanah-sport
Restart application servicesamanah-installer restart --directory /opt/amanah-sport
Read backend logsamanah-installer logs backend --directory /opt/amanah-sport
Follow backend logsamanah-installer logs backend --follow --directory /opt/amanah-sport
Read HTTPS/proxy logsamanah-installer logs proxy --directory /opt/amanah-sport
Create a backupamanah-installer backup /srv/amanah-backups --directory /opt/amanah-sport

Log service choices are backend, frontend, postgres, proxy, and waha. Pressing Ctrl+C stops following the log; it does not stop the container. WAHA is only present/running when the messaging profile is enabled.

stop causes application downtime while keeping volume data. start and restart do not restart the trial period. During a trial, a newly restarted process must obtain fresh online verification even if the trial has not expired; repeated restarts do not fix a licensing outage.

For operations without an installer shortcut, run the release helper from the installation directory:

Terminal
cd /opt/amanah-sport
python3 release.py validate
python3 release.py up
python3 release.py check

validate checks configuration. up applies/starts services and checks HTTPS. check tests the domain resolved by DNS at that time, so confirm that it points to the VPS being serviced. Use the helper for state changes to retain its configuration checks and operation lock.

5. Application restart, Docker restart, or host reboot

ActionEffectWhen to use it
amanah-installer restart …Restarts services for this Amanah installationAfter the relevant application/configuration issue is resolved
systemctl restart dockerRestarts the Docker daemon and may affect every Docker application on the VPSWhen diagnosis identifies a stalled or failed daemon
rebootRestarts the entire VPS and disconnects SSHPlanned OS/kernel maintenance or host recovery

Inspect Docker before restarting its daemon:

Terminal
systemctl is-active docker
systemctl status docker --no-pager
journalctl -u docker -n 100 --no-pager

If the daemon stopped and the underlying problem is resolved:

Terminal
systemctl start docker
amanah-installer start --directory /opt/amanah-sport

If a daemon restart is necessary, use a maintenance window, account for other applications on the VPS, then run Amanah status and doctor. After a host reboot, wait for SSH to return, check Docker, and inspect/start the Amanah installation. A successful host boot does not prove that application services are healthy.

6. Trace Docker problems

Start with status, doctor, and the logs for the failing component. For further inspection, use the correct installation directory and a shell without unintended COMPOSE_* overrides:

Terminal
cd /opt/amanah-sport
docker compose ps
docker compose logs --tail 100 backend frontend proxy
docker compose logs --tail 100 postgres
docker compose logs --tail 100 waha
docker stats --no-stream
df -h
df -i
free -h
docker system df

docker stats shows CPU/memory use; df -h checks disk capacity and df -i checks inodes. docker system df reports consumption; a large total does not mean all of that data is disposable.

For suspected memory exhaustion, obtain the backend container ID and replace CONTAINER_ID below with that actual ID:

Terminal
docker compose ps -q backend
docker inspect --format '{{.Name}} OOMKilled={{.State.OOMKilled}} Exit={{.State.ExitCode}} Restarts={{.RestartCount}}' CONTAINER_ID
journalctl -k -n 100 --no-pager

Use the selected inspection fields shown above. Unfiltered docker inspect and full docker compose config output can reveal environment secrets; do not paste them into support tickets. Before sharing application logs, redact tokens, passwords, personal data, customer phone numbers, chat contents, and unnecessary payment details.

Record the incident time, last action, release version, failing service, HTTP/error code, available storage/memory, and recent DNS/network changes. This is more useful than repeatedly restarting without identifying the cause.

7. DNS, HTTPS, ports, and server time

Replace booking.venue.example with your venue hostname:

Terminal
getent ahosts booking.venue.example
ss -lntp
curl --max-time 15 -I https://booking.venue.example/health
timedatectl status

If dig is available, compare the A and AAAA records. Check public DNS, cloud firewall/security-group rules for ports 80/443, and whether Nginx, Apache, or another container already owns those ports. Inspect proxy logs for certificate issuance failures. Do not expose PostgreSQL or WAHA publicly to fix HTTPS.

If you do not use IPv6 but an AAAA record points to a different host, correct DNS deliberately; testing IPv4 alone does not verify every visitor's route. If another CDN/proxy is present, match its TLS mode and proxy chain to the tested Caddy setup.

Keep the OS clock synchronized for TLS and server operations. If synchronization is disabled, restore it through the Ubuntu time service in use. Changing the local clock does not reset the trial; its end time is controlled by the licensing service. Do not move the clock backwards to extend access.

Also test from a network outside the VPS. Verify the application, HTTPS, and login over IPv4; if DNS publishes AAAA, repeat over IPv6. A public firewall blocking port 443 or an incorrect AAAA record can be missed by checking only one local path. Retain the network acceptance evidence before opening the application to customers.

8. License and connectivity issues

SymptomMeaning and next action
Not activated / setupThe installation has been reserved, but setup is incomplete. Continue only the installer stages identified as safe; do not accept real bookings yet.
INSTALLATION_NOT_FOUND / invalid credentialsInstallation identity and secret do not match the service. Confirm the directory and ask the operator to recover identity; do not create a new trial.
INSTALLATION_CONFLICTThe key is bound to another identity. Do not delete the database or attempt an automatic takeover.
NONCE_REUSEDA previous request was reused. The client must generate a fresh nonce on retry; do not copy an old response token into configuration.
LICENSE_EXPIREDThe trial ended. Activate a verified full purchase; restart, reinstall, restore, or clock changes do not extend the period.
LICENSE_REVOKEDThe central service revoked the license. Ask the operator to check the order/license status.
Verification unavailable / HTTP 503The licensing service or outbound connection is failing. Check DNS, TLS, outbound firewall rules, and service status; this differs from an expired trial.
HTTP 429Too many requests. Wait for the required backoff; avoid running concurrent resume/restart processes.
Signature, issuer, or release manifest rejectedFiles, verification keys, domain, or version do not match. Obtain the correct official release; do not disable verification to continue.

During a trial, the backend refreshes its lease periodically. A network interruption is tolerated only while the existing lease remains valid: at most one hour (60 minutes), never beyond the trial end. A new process must be online to obtain fresh permission. A full perpetual license follows a separate policy; expiration of annual Software Care (feature updates) or Monthly Server Maintenance (VPS Ops) never locks a perpetual full license.

If a key is lost or its issuance response was interrupted, contact the official Amanah team at [email protected] or WhatsApp +62 821-2190-9056 with your order or invoice reference. The operator can look up the same license and rotate its key, preserving the original trial. Receive the replacement key through a private channel.

If the entire installation identity is lost, the operator can bind the same license to the destination identity prepared by the installer. Activation and trial-end dates remain unchanged, and the old identity credentials are rejected at the next verification. Stop the source before moving VPS; do not operate two active copies. A revoked license cannot be recovered through key rotation or rebind.

When connectivity returns, run status and doctor; use start or resume only when that stage requires it. Do not manually change a license ID, key, secret, generation, expiry, or state file. An old backup does not undo central licensing decisions.

9. Common failures and recovery

ProblemDiagnosis and next step
Docker cannot connectCheck systemctl status docker, storage, and Docker's journal; start the daemon after resolving the cause.
port is already allocatedInspect ss -lntp and other containers. Move/stop the conflicting service according to the maintenance plan; do not make database ports public.
Image pull denied / unauthorizedCheck the official image name/digest and registry connectivity. Official images must pull without login; report any release requesting credentials to Amanah. Never use a shared publisher token or disable verification.
DNS lookup or outbound TLS failsCheck the resolver, OS clock, DNS provider, outbound proxy/firewall, and internet access. Disabling TLS verification is not a fix.
Full disk or exhausted inodesIdentify logs, images, media, and backups consuming space. Move backups according to agreed retention or expand storage; preserve required volumes and recovery points.
Container restart loop / OOMCheck logs, OOM state, memory, and workload. Adjust capacity/configuration; a brief running state does not resolve a restart loop.
Bootstrap login failsCheck whether the admin already exists. Bootstrap environment values only create the initial account; use supported account recovery rather than resetting the database.
WhatsApp cannot receive/sendCheck the messaging profile, WAHA health, phone pairing, active session, callback, and provider edition. Container health alone does not prove pairing.
Payment status does not updateCheck gateway credentials/mode, callback domain, backend logs, and provider transaction status. Do not manually approve again before checking for duplicates and the original state.
.release-operation.lockAn active lock means another operation is still running. Wait and inspect Docker activity. The lock file may remain after completion; the operating system releases its lock when the process exits. Never delete the file to bypass an active operation.
.release-initialize.pendingDatabase initialization/migrations did not finish and the helper blocks later operations. Preserve the state for diagnosis and use a new empty directory/project as directed. Do not remove the marker to force a partial database online.
.release-restore.pendingA restore failed after writes started. Startup is blocked; retain the failure evidence and use a new empty target. Do not delete the marker to force startup.
Restore refuses a populated targetThis is intentional. Use a new directory, Compose project name, empty database, and empty volumes; do not spontaneously clear old data.

Do not run docker compose down -v, docker system prune --volumes, or reset the database as routine troubleshooting. These actions can remove data or recovery materials that are still needed.

10. Routine backups

Terminal
amanah-installer backup /srv/amanah-backups --directory /opt/amanah-sport
cd /opt/amanah-sport
python3 release.py verify-backup /srv/amanah-backups/TIMESTAMP-ID

Replace TIMESTAMP-ID with the complete backup location printed by the helper. Backups temporarily stop writers, including the backend/workers and WAHA, create the database dump and media archive, and restart previously running services after completion or a handled failure. This causes downtime. If the VPS stops abruptly, inspect its state before bringing the application back online.

A complete backup contains the database, uploads, WhatsApp sessions, .env, Compose/Caddy files, metadata, and checksums. Format 2 also includes license.json when that identity file exists in the installation. Format 3 additionally preserves the completed installer journal and verified release archive for recovery and later upgrades. The media archive also includes the license cache volume (licensing); trial startup still needs online verification, while a valid perpetual cache follows the perpetual license policy. A .partial directory is not a recovery point. Caddy certificates are not included and will be issued again. Keep the release package and image pull access too. Older format 1 backups without identity require a separate identity recovery process.

The helper does not encrypt backups. Encrypt the storage/destination, restrict operator access, and keep an off-host copy. Databases, configuration, payment evidence, and WhatsApp sessions contain sensitive information. Set backup frequency, retention, failure alerts, and recipients; a manual backup does not install a schedule.

Test restoration regularly. A backup directory does not prove that its data can be recovered. Record completion time, verification results, off-host copy location, and restore-drill outcomes.

11. Restore, move to another VPS, or roll back

Restore into a new directory and Compose project with an empty database and empty volumes. Preserve the source until the target is accepted. Do not run initialize on a restore target or run two active copies against the same messaging/provider sessions.

  1. Verify a complete backup from a trusted source. Prepare the target VPS prerequisites and keep the official installer, release files, and image references available. Isolate provider connections during drills so the copy cannot send real messages or process real payments.
  2. Restore to a new location. The installer creates the target configuration and a new Compose project name:
Terminal
amanah-installer restore /srv/amanah-backups/TIMESTAMP-ID \
  --directory /opt/amanah-restore
  1. Restore starts PostgreSQL and restores data/media; application services remain stopped. A populated target is refused. If restoration fails after target data has been written, preserve that target for diagnosis and use another empty target for the next attempt.
  2. Format 2/3 backups restore license.json. Verify root:10001 ownership and mode 0640 as directed by the helper without displaying its contents. The trial keeps its original period and startup verifies online. Format 3 also preserves the installer journal and authenticated release archive. If identity does not match or an older backup lacks it, resolve recovery with the operator before opening traffic.
  3. Ensure only one installation uses the public domain/ports and provider sessions. Stop the source before switching traffic to the target. Review the target .env privately if its domain or provider callbacks must change; do not copy values into support logs.
  4. Start and check the recovered installation:
Terminal
amanah-installer start --directory /opt/amanah-restore
amanah-installer doctor --directory /opt/amanah-restore
  1. Test HTTPS, owner login, historical bookings/payments, configuration, media samples/checksums, invoices, and active integrations, including from outside the VPS. Reconcile transactions since the snapshot before reopening bookings.

For an older installation managed directly through the official release helper, python3 release.py restore BACKUP_PATH and its rollback alias restore into an already prepared empty target. Use the corresponding verified release procedure for that helper version. Downgrading images on an already-migrated database is not a safe rollback. An older backup can omit changes after its snapshot; account for that transaction window.

12. Upgrade the application version

An application upgrade differs from buying a license or adding branch capacity. Year 2+ feature upgrades are included with an active Software Care plan (optional annual renewal, separate from Monthly Server Maintenance / VPS Ops). For an installation completed by the installer, use:

Terminal
amanah-installer upgrade --directory /opt/amanah-sport \
  --backup-directory /srv/amanah-backups

The installer retrieves the current signed official manifest and verifies the package, version, and compatible backend/frontend digest pair. It verifies the installation identity, asks for owner login and confirmation, and creates a consistent backup before applying the images. Allow a downtime window. If the same release is already installed, no upgrade is needed. Finish an interrupted installation with resume before upgrading.

Acceptance checks include HTTPS, owner login, licensing, installation identity, and the expected release. If verification fails after changes, services are stopped and the recovery backup is reported. Restore to a new empty target; do not downgrade the migrated live database. Repeat the affected business workflows after the automated checks pass.

The shortcut supports compatible application image updates. Changes to the release helper, Compose/Caddy, infrastructure, backup contract, or PostgreSQL major version require a separate release migration procedure. Local edits to protected release files also need review. Do not replace PostgreSQL 17 with another major version through an ordinary tag edit.

For older installations without an installer journal, the official operator procedure may use the helper with a backend/frontend pair supplied and tested together:

Terminal
cd /opt/amanah-sport
python3 release.py upgrade \
  --backend-image ghcr.io/amanah-sport/backend@sha256:DIGEST_BACKEND \
  --frontend-image ghcr.io/amanah-sport/frontend@sha256:DIGEST_FRONTEND \
  --backup-directory /srv/amanah-backups

Replace placeholders with the official image references and full 64-character SHA-256 digests. This helper changes application images only; it does not authorize unrelated infrastructure changes or bypass the release migration procedure.

13. Acceptance records and verification

Privately retain the installer/release versions, image digests, domain, activation/trial end times, check results, and backup locations. Record remaining issues and who owns their resolution.

Local checks do not replace acceptance on the customer's VPS. Public DNS, the installer on Ubuntu, registry access, HTTPS, WhatsApp pairing, payment settlement, and recovery must be verified in the venue's environment. Use the validation report supplied with the release; one successful check does not prove the server is ready.

Before accepting customers, record a complete installation from the single executable, recovery after restart/reboot, correct domain/HTTPS, owner/staff access within their permissions, expiry and reactivation, verified payments/messages, and one successful backup-restore drill. Use these actual results to accept the installation.

Official Technical Support & Legal Links

Official installer handovers, license keys, key rotation, and verified support happen strictly through the channels below.

Back to top ↑