Deployment guide

This guide shows you how to install AxoConsole on a local, on-premises virtual machine using k3s and Helm. Installation of other components like the ingress controller and the cert-manager is also included. Since this is a single instance deployment, we don’t recommend using it in production environments. For additional steps and configurations needed in production environments, contact our support team.

To deploy AxoConsole in an air-gapped environment, see Air-gapped.

At a high level, the deployment consists of the following steps:

1. Preparing a virtual machine.

2. Running the installation script on the virtual machine that deploys:

   • Kubernetes
   • cert-manager and Traefik
   • AxoConsole

   Any of these components can be skipped if already installed.

3. Basic authentication with admin user and password is configured by default. You can also configure other common authentication methods like LDAP, Github and Google.

4. Before deploying AxoRouter describes the steps you have to complete on a host before deploying AxoRouter on it. These steps are specific to on-premises AxoConsole deployments, and aren’t needed when using the SaaS AxoConsole.

Prerequisites

To install AxoConsole, you’ll need the following:

• The URL for the AxoConsole installation script. You’ll receive this URL from our team. You can request it using the contact form.

  CAUTION:

  Don’t start the Install AxoConsole process until you’ve received the URL.

• A license key for AxoConsole. You’ll receive this from our team. You can request it using the contact form.

• A host that meets the system requirements.

• Network access set up for the host.

System requirements

Supported platforms:

• Ubuntu 24.04 and 26.04,
• Red Hat Enterprise Linux 9.4 or newer and 10.

Other compatible and derivative distributions (for example, AlmaLinux or Rocky Linux) should work as well, but we don’t test them explicitly.

The virtual machine (VM) must have at least:

• A Minimum setup with 4 vCPU (x86_64-based), 8 GB RAM, and 100 GB disk space can handle about 100 AxoRouter instances and 1000 data source hosts.

• A real-life production scenario that handles 100 AxoRouter and 3000 data source hosts with 30-day metric retention would need:

  • 16 vCPU (x86_64-based)
  • 16 GB RAM
  • 250 GB disk space

For details on sizing, contact our support team.

You’ll need to have access to a user with sudo privileges.

Network access

The host must be able to access the following domains related to the AxoConsole:

• When using AxoConsole SaaS:

  • <your-tenant-id>.cloud.axoflow.io: HTTPS traffic on TCP port 443, needed to download the binaries for Axoflow software (like Axolet and AxoRouter).
  • kcp.<your-tenant-id>.cloud.axoflow.io: HTTPS (mutual TLS) traffic on TCP port 443 for management traffic.
  • telemetry.<your-tenant-id>.cloud.axoflow.io: HTTPS (mutual TLS) traffic on TCP port 443, where Axolet sends the metrics of the host.
  • us-docker.pkg.dev: HTTPS traffic on TCP port 443, but only if you’re forcing the installation script to pull the container images from the public repository. The Axolet and AxoRouter for Linux installation scripts download the images directly from AxoConsole.

• When using an on-premises AxoConsole:

  • The following domains should point to AxoConsole IP address to access Axoflow from your desktop and AxoRouter hosts:

    • your-host.your-domain: The main domain of your AxoConsole deployment.
    • idp.your-host.your-domain: A subdomain for the identity provider. Only Dex uses this subdomain. The built-in identity provider uses the /idp path of the main domain.
    • kcp.your-host.your-domain: A subdomain for management traffic.
    • telemetry.your-host.your-domain: A subdomain for agent telemetry.

  • The AxoConsole host must have the following Open Ports:

    • 80 TCP: Traefik ingress (HTTP, redirected to HTTPS).
    • 443 TCP: HTTPS for the AxoConsole UI, API, and all web traffic.

• When installing Axoflow agent for Windows or Linux:

  • github.com: HTTPS traffic on TCP port 443, for downloading installer packages.

Install AxoConsole

1. Download the installation script from the URL you’ve received from the Axoflow Support Team.

2. Transfer the file to the host where you want to install AxoConsole.

3. Run the installation script with your license key and the domain name for your AxoConsole deployment.

   Note Re-running the installer will reuse any existing or modified manifests or user settings (for example, authentication settings added to /var/lib/rancher/k3s/server/manifests/axoflow-config.yaml) available on the host.

   sudo LICENSE_KEY=<your-license-key> BASE_HOSTNAME=<axoconsole-domain-name> AXOFLOW_VERSION=0.90.0 bash ./axoflow-install.sh ‐‐no-airgap

   Note

   If you omit BASE_HOSTNAME, the installer probes whether <VM_IP>.nip.io resolves and offers it as the default. nip.io is a free wildcard DNS service. It’s useful for testing and demos, because AxoConsole and all its subdomains resolve without any DNS or /etc/hosts configuration. For production deployments, use a proper domain name.

   BASE_HOSTNAME must be a lowercase DNS name (a-z, 0-9, -, and dots), not an IP address.

   You can use the following flags as needed for your environment.

   • --step: Prompt before each step

   • --dry-run: Show what would be done without executing anything

   • --skip-k3s: Skip k3s installation (already installed)

   • --skip-cert-manager: Skip cert-manager installation

   • --disable-traefik: Disable the built-in Traefik ingress controller of k3s. Use this option if you use a custom ingress controller. The installer also skips the CoreDNS rewrite of the base hostname, so the cluster DNS must resolve the base hostname to your ingress controller.

   • --skip-nip-io: Skip the automatic <VM_IP>.nip.io DNS probe and use axoflow.local as the default base hostname.

   • --idp-bootstrap: Don’t create the admin user of the built-in identity provider. The first user who registers at https://<axoconsole-domain-name> becomes the admin, so register before exposing the host to other users. Environment variable: AXOIDP_BOOTSTRAP=true.

   • --idp-admin-password: Prompt for the password of the admin user instead of generating a random one. The installer stores only a bcrypt hash of the password. Online installations without the bundle need the htpasswd tool on the host to hash the password. The prompt needs an interactive terminal. For non-interactive installations, use one of the following environment variables instead:

     • AXOIDP_ADMIN_PASSWORD=<password>: The password of the admin user.
     • AXOIDP_ADMIN_PASSWORD_HASH=<hash>: A bcrypt hash of the password. Create the hash on a different host, for example, with htpasswd -nbB admin '<password>' | cut -d: -f2-. With this variable, the password doesn’t get to the AxoConsole host, and the host doesn’t need htpasswd.

   • --diagnose [namespace]: Inspect pods that are not ready and explain why (image-pull errors, configuration issues, crashes). Runs automatically on a timeout; use on demand after a failed install.

   • --uninstall: Uninstall AxoConsole. The installer prompts before each step (removing workloads, deleting data, and removing k3s), so you can stop at any point. See Uninstall AxoConsole.

   Advanced flags:

   • --skip-images: Skip container image import entirely. Use when images are already loaded into k3s.
   • --image-mode bundle|component|skip: Control how container images are imported. bundle (default) imports pre-packaged image tarballs; component imports one image per component; skip skips import.
   • --prepare-env: Install only k3s, cert-manager, and Traefik, and skip AxoConsole. Use for a two-phase install where you want to configure the environment before deploying AxoConsole.
   • --ignore-requirements: Bypass hardware requirement checks.

4. If needed, follow the on-screen instructions. For a test installation, you can usually use the default values. For recommendations for a production environment, contact our support team.

5. Wait a few minutes until everything is installed.

   In case of any errors, check Troubleshooting for tips.

6. If you didn’t use the --idp-bootstrap or the --idp-admin-password flag, the script asks to show the password of the default admin user. Record the password. You need it to log in to AxoConsole.

   ...
   [2026-06-02 20:44:28] [INFO ] All pods in axoflow are ready/complete
   [2026-06-02 20:44:28] [INFO ] Axoflow is healthy
   [2026-06-02 20:44:28] [INFO ] Access the UI at: https://<axoconsole-domain-name>
   Show admin credentials? [y/N]: y
   Username: admin
   Password: MzGIjuWKjXOtiRs4

   If needed, later you can retrieve the password by running:

   kubectl -n "${AXOFLOW_NAMESPACE}" get secret axoidp-admin \
   -o go-template='Username: {{ .data.username | base64decode }}{{ printf "\n" }}Password: {{ .data.password | base64decode }}{{ printf "\n" }}'

   Note

   • If you used the --idp-bootstrap flag, the installer doesn’t create the admin user or the axoidp-admin secret. Open the AxoConsole URL and register the first user. This user becomes the admin.
   • If you set the password with --idp-admin-password (or the AXOIDP_ADMIN_PASSWORD or AXOIDP_ADMIN_PASSWORD_HASH environment variable), log in as admin with the password that you set.

Log in to AxoConsole

1. If your desktop can’t resolve the domain name of AxoConsole, add the domain name to the /etc/hosts file of your desktop. Use the following format, with an IP address of AxoConsole that your desktop can access.

   <AXOFLOW-CONSOLE-IP-ADDRESS> <your-host.your-domain> kcp.<your-host.your-domain> telemetry.<your-host.your-domain>

2. Open the https://<your-host.your-domain> URL in your browser.

3. The on-premises deployment of AxoConsole shows a self-signed certificate. If your browser complains about the related risks, accept it.

4. Log in to AxoConsole as admin, with the password from the installation step. If you used the --idp-bootstrap flag, register the first user, or log in with the user that you registered.

Prepare AxoRouter hosts

AxoConsole service reference

Troubleshooting

• If you get the [ERROR] Timed out waiting for k3s node to be Ready error message, increase the timeout limit by running K3S_TIMEOUT=180, then rerun the installation script.

In case of other errors, run the following command to create a debug package from the cluster, and contact our support team.

sudo k3s kubectl cluster-info dump --all-namespaces  --output-directory=./cluster-dump && tar -czvf cluster-dump.tar.gz cluster-dump

Uninstall AxoConsole

To uninstall AxoConsole, run the installer with the --uninstall flag:

sudo ./axoflow-install.sh --uninstall

The uninstaller prompts before each step and requires separate confirmation for:

1. Removing the AxoConsole workloads and manifests

2. Deleting stored data (namespace and PersistentVolumeClaims) — irreversible

   CAUTION:

   Hazard of data loss!

   Confirming step 2 permanently deletes all stored data.

3. Removing k3s

   CAUTION:

   Hazard of data loss!

   If you’re using k3s to run other software apart from AxoConsole, decline step 3 to keep k3s in place.

The uninstaller is safe to run on a partial or incomplete installation.