Install aseStack

This guide installs the current CDN release on a fresh Ubuntu or Debian amd64 server. The result is a production-mode Go service with the compiled dashboard, a local managed-server agent, a daily local backup timer, and the aseStack command-line helper.

Production-testable software

aseStack is ready for controlled production trials, but it is not yet a finished panel. Start on a new or recoverable host, keep independent backups, and leave write-capable guards disabled until you have tested the associated workflow.

1. Prepare the controller name

Choose the public HTTPS name for the controller. This guide uses:

control.example.com

Create its DNS record before requesting a certificate. The record should point to the server that will run the reverse proxy. When the proxy and aseStack are on the same host, aseStack can remain bound to 127.0.0.1:15173.

Review the requirements before continuing.

2. Confirm the host

Connect to the server and check the OS, architecture, init system, and available disk space:

cat /etc/os-release
uname -m
systemctl --version | head -n 1
df -h / /var /opt

The standard release path expects Ubuntu or Debian, x86_64, and systemd.

The small bootstrap wrapper needs curl, python3, and a checksum tool before it can verify the exact sidecar binding and GitHub immutable-release asset digests. If a prerequisite is missing, install it first:

sudo apt-get update
sudo apt-get install -y curl python3 coreutils ca-certificates

3. Run the installer

Prepare the current release on a trusted operator workstation with authenticated GitHub CLI access. Download from the CDN and verify both bootstrap files against independent GitHub release attestations before transferring or executing them:

set -euo pipefail
tag="$(gh release view --repo asetho/aseStack --json tagName --jq .tagName)"
curl -fLO https://cdn.asestack.dev/latest/quick-start.sh
curl -fLO https://cdn.asestack.dev/latest/quick-start.sh.sha256
sha256sum -c quick-start.sh.sha256
gh release verify-asset "$tag" quick-start.sh --repo asetho/aseStack
gh release verify-asset "$tag" quick-start.sh.sha256 --repo asetho/aseStack
umask 077
gh api "repos/asetho/aseStack/releases/tags/$tag" > release.json

On macOS, use shasum -a 256 -c quick-start.sh.sha256. Transfer these three verified, non-secret files to the server through a trusted channel, then run:

sudo install -o root -g root -m 0600 release.json /root/asestack-release.json
sudo ASESTACK_PUBLIC_URL=https://control.example.com \
  ASESTACK_GITHUB_RELEASE_API_URL=file:///root/asestack-release.json \
  ASESTACK_RELEASE_BASE_URL=https://cdn.asestack.dev/latest bash ./quick-start.sh

No GitHub credential is placed on the new host. Archive downloads default to the CDN while the protected immutable-release JSON binds names, URLs, sizes, and digests. A CDN-hosted checksum alone is not installer provenance: do not omit the workstation release attestation checks. The CDN publishes only the current latest/ channel; historical releases need explicit artifact URLs or files supplied by the operator. If publication advances between downloads, verification fails closed; repeat with matching files. The Settings update panel uses the public CDN metadata without a GitHub credential. Follow Optional direct GitHub update status only when the controller should query GitHub directly.

On a fresh host, the installer:

1. Installs any missing base tools through apt.
2. Downloads the release archive and verifies its exact-filename checksum plus GitHub immutable-release digest and size.
3. Extracts the application to /opt/asestack.
4. Creates /etc/asestack/asestack.env with mode 0600.
5. Generates an initial owner password and backup credential key.
6. Installs and starts asestack.service.
7. Enables the daily asestack-backup.timer.
8. Installs the asestack CLI and, when the name is available, the shorter ase alias.
9. Enrolls the controller itself as the local managed server and starts asestack-agent.service.

The fresh-install output includes lines similar to:

Initial admin email: admin@asestack.local
Initial admin password: <generated password>

Save the generated password in a password manager before closing the terminal. Do not paste the installer output into tickets or chat because it contains the initial credential.

4. Verify the local services

Check the controller, local agent, and backup timer:

sudo systemctl is-active asestack
sudo systemctl is-active asestack-agent
sudo systemctl is-enabled asestack-backup.timer
curl -fsS http://127.0.0.1:15173/api/v1/health

The first two commands should print active, the timer should print enabled, and the health endpoint should return JSON. If a service is still starting, inspect its recent log:

sudo journalctl -u asestack -n 50 --no-pager
sudo journalctl -u asestack-agent -n 50 --no-pager

You can also use the installed helper:

sudo asestack status
asestack health

5. Add HTTPS

At this point aseStack intentionally listens only on the controller's loopback interface. Configure a local reverse proxy for control.example.com; do not open port 15173 publicly.

Follow Reverse proxy and HTTPS, then confirm both the local and public health endpoints:

curl -fsS http://127.0.0.1:15173/api/v1/health
curl -fsS https://control.example.com/api/v1/health

Installation paths

Path	Purpose
/opt/asestack	Installed release
/opt/asestack/bin/asestack-server	Controller binary
/opt/asestack/bin/asestack-agent	Bundled agent binary used for the local agent
/etc/asestack/asestack.env	Controller environment and secrets
/etc/asestack/agent/agent.env	Local agent configuration
/var/lib/asestack	Controller data
/var/backups/asestack	Local backups

The environment file is the authoritative startup configuration for asestack.service. Keep it root-readable and use the configuration reference before changing defaults.

A proxy on another host

The recommended layout keeps the proxy on the controller and leaves aseStack on loopback. If the proxy must run on another trusted private host, bind aseStack to the controller's private address during installation:

sudo \
  ASESTACK_PUBLIC_URL=https://control.example.com \
  ASESTACK_BIND_ADDR=10.0.0.10:15173 \
  ASESTACK_TRUSTED_PROXY_CIDRS=10.0.0.20/32 \
  bash ./quick-start.sh

Replace 10.0.0.20/32 with the proxy's exact address (or an IPv6 /128) and firewall that private listener so only the proxy can reach it. Wildcard, public, and hostname listener values are rejected because the built-in server uses HTTP.

Existing installations

Do not use a fresh-install workflow as an unattended updater. Existing installations have a dedicated update path that displays the installed and available versions and requires confirmation:

sudo asestack update

The installer creates a local control-plane backup before replacing an existing application directory. Do not bypass that guard unless you are handling a deliberate recovery situation. See Update and CLI operations.

Next, complete the first-login checklist.