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:
sha256sum /root/amanah-installerOnce the checksum matches, install the executable somewhere convenient for future use:
install -m 0755 /root/amanah-installer /usr/local/bin/amanah-installer
amanah-installer install --directory /opt/amanah-sportFollow 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:
| Choice | Collected during installation | Remaining onboarding |
|---|---|---|
| Enable the local messaging service | Pair the phone in admin and test send/receive | |
| Google login | OAuth client ID and secret | Register the origin and https://booking.venue.example/api/auth/google/callback with Google, then test login |
| Telegram | Optional numeric bot ID for login | Connect the bot/session in admin and authorize the login domain with the provider |
| Payments | Manual, Midtrans, or Xendit | Enter credentials and sandbox/production mode in branch settings; test a payment and its callback |
| None, SMTP, Resend, or SendGrid; verified sender and applicable credentials | Verify 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:
amanah-installer resume --directory /opt/amanah-sportIf 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.
- Open the booking domain over HTTPS and sign in as the owner. Verify admin access, not just the login page.
- 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.
- 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.
- 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.
- 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.
- Configure Telegram, AI, email, OAuth, and Web Push only when used.
EMAIL_PROVIDER=nonemeans email is disabled. PWA and Web Push require HTTPS and compatible devices and permissions. - Create staff accounts with the appropriate branch scope and permissions; confirm that access to other branches is denied.
- 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.
| Task | Command |
|---|---|
| View application status | amanah-installer status --directory /opt/amanah-sport |
| Run diagnostics | amanah-installer doctor --directory /opt/amanah-sport |
| Start application services | amanah-installer start --directory /opt/amanah-sport |
| Stop application services | amanah-installer stop --directory /opt/amanah-sport |
| Restart application services | amanah-installer restart --directory /opt/amanah-sport |
| Read backend logs | amanah-installer logs backend --directory /opt/amanah-sport |
| Follow backend logs | amanah-installer logs backend --follow --directory /opt/amanah-sport |
| Read HTTPS/proxy logs | amanah-installer logs proxy --directory /opt/amanah-sport |
| Create a backup | amanah-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:
cd /opt/amanah-sport
python3 release.py validate
python3 release.py up
python3 release.py checkvalidate 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
| Action | Effect | When to use it |
|---|---|---|
amanah-installer restart … | Restarts services for this Amanah installation | After the relevant application/configuration issue is resolved |
systemctl restart docker | Restarts the Docker daemon and may affect every Docker application on the VPS | When diagnosis identifies a stalled or failed daemon |
reboot | Restarts the entire VPS and disconnects SSH | Planned OS/kernel maintenance or host recovery |
Inspect Docker before restarting its daemon:
systemctl is-active docker
systemctl status docker --no-pager
journalctl -u docker -n 100 --no-pagerIf the daemon stopped and the underlying problem is resolved:
systemctl start docker
amanah-installer start --directory /opt/amanah-sportIf 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:
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 dfdocker 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:
docker compose ps -q backend
docker inspect --format '{{.Name}} OOMKilled={{.State.OOMKilled}} Exit={{.State.ExitCode}} Restarts={{.RestartCount}}' CONTAINER_ID
journalctl -k -n 100 --no-pagerUse 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:
getent ahosts booking.venue.example
ss -lntp
curl --max-time 15 -I https://booking.venue.example/health
timedatectl statusIf 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
| Symptom | Meaning and next action |
|---|---|
| Not activated / setup | The 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 credentials | Installation 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_CONFLICT | The key is bound to another identity. Do not delete the database or attempt an automatic takeover. |
NONCE_REUSED | A previous request was reused. The client must generate a fresh nonce on retry; do not copy an old response token into configuration. |
LICENSE_EXPIRED | The trial ended. Activate a verified full purchase; restart, reinstall, restore, or clock changes do not extend the period. |
LICENSE_REVOKED | The central service revoked the license. Ask the operator to check the order/license status. |
| Verification unavailable / HTTP 503 | The licensing service or outbound connection is failing. Check DNS, TLS, outbound firewall rules, and service status; this differs from an expired trial. |
| HTTP 429 | Too many requests. Wait for the required backoff; avoid running concurrent resume/restart processes. |
| Signature, issuer, or release manifest rejected | Files, 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
| Problem | Diagnosis and next step |
|---|---|
| Docker cannot connect | Check systemctl status docker, storage, and Docker's journal; start the daemon after resolving the cause. |
port is already allocated | Inspect ss -lntp and other containers. Move/stop the conflicting service according to the maintenance plan; do not make database ports public. |
| Image pull denied / unauthorized | Check 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 fails | Check the resolver, OS clock, DNS provider, outbound proxy/firewall, and internet access. Disabling TLS verification is not a fix. |
| Full disk or exhausted inodes | Identify 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 / OOM | Check logs, OOM state, memory, and workload. Adjust capacity/configuration; a brief running state does not resolve a restart loop. |
| Bootstrap login fails | Check 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/send | Check the messaging profile, WAHA health, phone pairing, active session, callback, and provider edition. Container health alone does not prove pairing. |
| Payment status does not update | Check 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.lock | An 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.pending | Database 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.pending | A 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 target | This 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
amanah-installer backup /srv/amanah-backups --directory /opt/amanah-sport
cd /opt/amanah-sport
python3 release.py verify-backup /srv/amanah-backups/TIMESTAMP-IDReplace 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.
- 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.
- Restore to a new location. The installer creates the target configuration and a new Compose project name:
amanah-installer restore /srv/amanah-backups/TIMESTAMP-ID \
--directory /opt/amanah-restore- 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.
- Format 2/3 backups restore
license.json. Verifyroot:10001ownership and mode0640as 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. - Ensure only one installation uses the public domain/ports and provider sessions. Stop the source before switching traffic to the target. Review the target
.envprivately if its domain or provider callbacks must change; do not copy values into support logs. - Start and check the recovered installation:
amanah-installer start --directory /opt/amanah-restore
amanah-installer doctor --directory /opt/amanah-restore- 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:
amanah-installer upgrade --directory /opt/amanah-sport \
--backup-directory /srv/amanah-backupsThe 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:
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-backupsReplace 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.