Skip to content

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 and either sha256sum or shasum before it can verify and start the full installer. Standard Ubuntu and Debian images normally include the checksum tool. If either prerequisite is missing, install it first:

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

3. Run the installer

Run the checksum-verified CDN installer and set the public controller URL at installation time:

curl -fsSL https://cdn.asestack.dev/install.sh \
  | sudo ASESTACK_PUBLIC_URL=https://control.example.com bash

On a fresh host, the installer:

  1. Installs any missing base tools through apt.
  2. Downloads and verifies the quick-start script and release archive.
  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:

curl -fsSL https://cdn.asestack.dev/install.sh \
  | sudo \
      ASESTACK_PUBLIC_URL=https://control.example.com \
      ASESTACK_BIND_ADDR=10.0.0.10:15173 \
      bash

Firewall that private listener so only the proxy can reach it. Never bind port 15173 to a public interface without an equally narrow network control.

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.