> ## Documentation Index > Fetch the complete documentation index at: https://arize-ax.mintlify.site/docs/llms.txt > Use this file to discover all available pages before exploring further. # Installation on Single Host > Step-by-step guide to install Arize AX on a single VM using k3s for testing or development. ## Overview This process is **not** for production. Use it only for testing or development. This guide walks you through installing Arize AX on a single host (one VM) using [k3s](https://k3s.io/). You will install k3s and Helm, point Arize AX at an S3-compatible object store, then deploy Arize AX from the distribution. Throughout this section, **distribution archive** means the **Arize AX release tarball** you download with your JWT (Helm chart, `arize.sh`, examples, and offline HTML docs). Follow the sections in order: VM -> k3s/Helm -> object storage -> distribution -> install -> ingress -> validate. ## Prerequisites Before starting, have the following ready: * **Arize AX distribution access** — JWT token for downloading the distribution from Arize AI * **Passwords and secrets** — You will choose a Postgres password and encryption key, and collect S3-compatible object storage credentials (all secret-bearing values base64-encoded in `values.yaml`) * **Organization name** — Name of your organization or company (for `values.yaml`) * **App URL** — The URL you will use to reach the Arize AX UI (e.g. `https://arize-app.yourdomain.com`). This can be a hostname you map to a **private** IP (see Step 8) if the VM has no public address. * **Network access to the VM** — If the VM only has a **private IP** (for example `10.x.x.x`, `172.16.x.x`, or `192.168.x.x`), your browser, SDKs, and any clients must run on a host that can reach that address (same VPC or subnet, site-to-site VPN, or client VPN into the cloud network). You do not need a public IP for this guide. ## Step 1: Create the virtual machine Create a single VM with these specifications: | Requirement | Specification | | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Size** | 16 vCPU, 128 GB RAM — e.g. `n2d-highmem-16` (GCP), `r7a.4xlarge` (AWS), `Standard_E16s_v5` (Azure) | | **OS** | Debian base image | | **Boot disk** | 500 GB | | **Network** | Allow HTTP and HTTPS traffic to the VM. If the machine uses a private IP only, restrict ingress to trusted CIDRs (for example your VPC, office, or VPN range) instead of the open internet. If the VM has a public IP, you can allow HTTP/HTTPS from the internet or from specific IPs, depending on your policy. | | **Access** | SSH (port 22). Add firewall rules and an SSH key as required by your cloud provider. For a private-IP-only host, allow SSH from your bastion, VPN, or admin network. | ## Step 2: Install k3s SSH into the machine, then run: ```bash theme={null} curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--write-kubeconfig-mode=644" sh - && \ mkdir -p ~/.kube && \ sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config && \ sudo chown $USER ~/.kube/config && \ chmod 600 ~/.kube/config ``` **Verify:** Run `kubectl get nodes`. You should see your node with status `Ready` and role `control-plane`, for example: ``` NAME STATUS ROLES AGE VERSION Ready control-plane 176m v1.34.5+k3s1 ``` ## Step 3: Install Helm ```bash theme={null} curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash ``` **Verify:** Run `helm version`. You should see JSON output with `BuildInfo` for your Helm installation. ## Step 4: Prepare object storage Arize AX needs S3-compatible object storage for Gazette and ArizeDB data. For a single-host development install, use the same object storage endpoint your platform team supports for testing, or a short-lived S3-compatible endpoint dedicated to this install. Create or collect: * One bucket for Gazette data, for example `gazette-bucket`. * One bucket for ArizeDB data, for example `adb-bucket`. * An endpoint URL reachable from the k3s node. * An access key and secret key with read/write access to both buckets. You will put these values in `values.yaml` in Step 6. ## Step 5: Retrieve the Arize AX distribution Create a release folder, download the distribution, and extract it. Replace `` with your actual JWT. ```bash theme={null} VERSION=${1:-$(curl -s https://arize.com/docs/ax/selfhosting/on-premise-releases | grep -Eo 'Release [0-9]+\.[0-9]+\.[0-9]+' | head -1 | awk '{print $2}')} mkdir arize-release-$VERSION && cd arize-release-$VERSION URL=https://ch.hub.arize.com/dist JWT="" curl -H "Authorization: Bearer $JWT" "$URL/distributions/arize-distribution-$VERSION.tar" --output "arize-distribution-$VERSION.tar" tar xvf *.tar ``` Stay in the release directory you created (`arize-release-$VERSION`). After extraction, it should contain `arize.sh`, `arize-operator-chart.tgz`, `docs/`, and `examples/`. ## Step 6: Create values.yaml From the extracted release directory that contains `arize.sh`, create `values.yaml` by editing the placeholders below and pasting the result into your terminal. All values marked “(base64 encoded)” must be base64-encoded. * **hubJwt:** Your runtime registry JWT (base64) * **postgresPassword:** A password you choose (base64) * **cephS3AccessKeyId:** S3-compatible object storage access key ID (base64) * **cephS3SecretAccessKey:** S3-compatible object storage secret access key (base64) * **cipherKey:** An encryption key you generate (base64) * **appBaseUrl:** The URL where you will access the Arize AX UI ```bash theme={null} cat > values.yaml << 'EOF' cloud: "ceph" clusterName: "default" hubJwt: "" gazetteBucket: "gazette-bucket" druidBucket: "adb-bucket" postgresPassword: "" organizationName: "" clusterSizing: "nonha" cephS3Endpoint: "" cephS3AccessKeyId: "" cephS3SecretAccessKey: "" cipherKey: "" storageClassCephSsd: "local-path" storageClassCephStandard: "local-path" ingressMode: "notls" # The URL used to reach the Arize AX UI once ingress endpoints are created # Use the same hostname you will put in /etc/hosts (Step 8), e.g. https://arize-app.example.local # Private-IP only: the hostname must resolve (via hosts file or DNS) to the VM's private IP for clients on that network appBaseUrl: "https://" # Only required if using a private docker registry pushRegistry: "" pullRegistry: "" EOF ``` ## Step 7: Install Arize AX From the same release directory, run: ```bash theme={null} ./arize.sh install ``` This installs the Arize AX Helm chart and deploys Arize AX on the single host. When the script completes successfully, Arize AX is now up and running in your k3s cluster. You can run `kubectl get pods -n arize` to see all pods in a running state. ## Step 8: Configure ingress Ingress exposes the Arize AX UI over HTTPS. You can use any certificate; this step uses a **self-signed certificate** for a low-effort setup. You can choose any domain (e.g. `arize-app.example.local`) — no real DNS record is required because you will use `/etc/hosts` to point the hostname to your VM. **Private IP only:** If the VM has **no public IP**, use the VM’s **private** address in `/etc/hosts` on every client that should open the UI or send data (your laptop on VPN, a jump host, or a build agent in the same VPC). The certificate and ingress hostnames stay the same; only the IP you map must be reachable from that client. ### 8a. Generate a self-signed certificate From the home directory, generate the cert. Replace `` with the domain you want to use (e.g. `example.local`). ```bash theme={null} openssl req -x509 -nodes -days 365 -newkey rsa:2048 \ -out tls.crt \ -keyout tls.key \ -subj "/CN=arize-app./O=Arize" -addext "subjectAltName = DNS:arize-app." ``` ### 8b. Get base64 values for the ingress manifests You will paste these values into the ingress YAML in the next step. Run: ```bash theme={null} base64 -w 0 tls.crt # use this for tls.crt in the manifest base64 -w 0 tls.key # use this for tls.key in the manifest ``` Copy each command’s output and keep it handy. ### 8c. Create and apply the ingress manifests Create an `ingress` directory and an `ingress.yaml` file. In the manifest below, replace: * **``** — The same domain you used in the certificate (e.g. `example.local`) * **``** — The full output of `base64 -w 0 tls.crt` * **``** — The full output of `base64 -w 0 tls.key` Then apply the file. ```bash theme={null} mkdir -p ingress && cd ingress cat > ingress.yaml << 'EOF' apiVersion: v1 kind: Secret metadata: name: arize-app-services-tls namespace: arize type: kubernetes.io/tls data: tls.crt: "" tls.key: "" apiVersion: v1 kind: Secret metadata: name: default-ingress-cert namespace: kube-system type: kubernetes.io/tls data: tls.crt: "" tls.key: "" apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: arize-app-services namespace: arize annotations: traefik.ingress.kubernetes.io/router.entrypoints: websecure spec: ingressClassName: traefik tls: - hosts: - arize-app. secretName: arize-app-services-tls rules: - host: arize-app. http: paths: - path: / pathType: Prefix backend: service: name: internalendpoints-app port: number: 443 apiVersion: traefik.io/v1alpha1 kind: IngressRoute metadata: name: arize-app namespace: arize spec: entryPoints: - websecure tls: secretName: arize-app-services-tls routes: - match: Host(`arize-app.`) kind: Rule services: - name: internalendpoints-app port: 443 apiVersion: traefik.io/v1alpha1 kind: TLSStore metadata: name: default namespace: kube-system spec: defaultCertificate: secretName: default-ingress-cert EOF kubectl apply -f ingress.yaml ``` ### 8d. Point the hostname to your VM and open the UI On each machine where you want to use the Arize AX UI (your laptop or another host), add a line to `/etc/hosts` so `arize-app.` resolves to the VM’s IP. This replaces a DNS record for testing. 1. Edit hosts (e.g. `sudo vi /etc/hosts` or `sudo nano /etc/hosts`). 2. Add a line: ` arize-app.`\ Use the same domain as in the certificate and ingress. **Which IP to use** * **Public IP:** If your cloud VM has a public address, use that IP in `/etc/hosts` from any client that can reach it (subject to your security group or firewall rules). * **Private IP only:** If the VM has **only** a private IP, use that private address. The client must be on a network that can route to it (for example same VPC, peered network, or connected VPN). If you reach the VM only via SSH through a bastion, you still need a path for HTTPS (port 443) from the browser/SDK machine to the Arize AX node—either run the browser on a host inside the VPC, use VPN, or forward ports with `ssh -L` and point `localhost` in `/etc/hosts` to match your tunnel setup. Example: ``` # Existing entries (leave as-is) 127.0.0.1 localhost ::1 localhost # Arize AX single-host VM (public or private IP — use the address your client can reach) arize-app. ``` **Verify:** In your browser, go to `https://arize-app.`. You should see the Arize AX login page. Accept the self-signed certificate warning if prompted, then sign in with your initial admin credentials. You can now use Arize AX. ## Step 9: Validate deployment The distribution includes example scripts under `examples/sdk`. Use them to confirm the cluster can receive traces. * **Certificate:** The deployment uses a self-signed cert. Have the certificate (e.g. `tls.crt`) available on the machine where you run the script, or configure the script to skip TLS verification if it supports that. * **Network:** Run the script from a host that can reach the VM’s **reachable** address for HTTPS (public IP or private IP). If the VM uses only a **private IP**, run the SDK from a host on the same VPC/VPN or with routing to that host, and use the same hostname in `/etc/hosts` (or DNS) as in `appBaseUrl`. From the extracted release directory, run the HTTP trace sample: ```bash theme={null} cd examples/sdk # Use the script’s options to point at your Arize AX endpoint and cert if required python trace_sample_http.py ``` If the script runs without errors and traces appear in the Arize AX UI, the deployment is working correctly.