Skip to content

Single VM Setup (POC Only)#

⚠️ NOT PRODUCTION READY - This setup uses a single VM with K3s (lightweight Kubernetes) and is intended for proof-of-concept and evaluation purposes only. It does not provide high availability, failover, or rolling maintenance capabilities. For production deployments, use a production Kubernetes cluster - either a new RKE2 multi-node cluster or an existing standard cluster.

This guide walks through deploying Ametnes Platform services on a single Ubuntu VM with K3s. It is designed for DevOps engineers, system administrators, or technical teams evaluating the platform in their own environment.

Prerequisites#

Requirement Minimum specification
OS Ubuntu 20.04 LTS or later
CPU 4 vCPUs
RAM 8 GB
Storage 100 GB
Network Outbound HTTPS (443) access to the Ametnes platform; inbound HTTPS (443) if service endpoints will be accessed from outside the VM's network. Inbound SSH (22) is only needed if you will administer the VM over SSH.

The CPU, RAM, and storage values above are minimums, not recommendations. Size the VM according to the services you intend to deploy; production workloads generally need more.

You also need:

  • SSH access to the VM with sudo privileges. This is only needed for you to run the Ametnes agent installation.
  • An outbound internet connection from the VM to the Ametnes platform. The Ametnes control plane does not connect to the VM; the cloud agent installed in Step 3 establishes an outbound connection to the platform.
  • An IP address to advertise as the external address for service endpoints. This can be a public IP for cloud VMs or a private IP for on-premise environments; it does not need to be reachable from the Ametnes control plane. For cloud VMs, use a static/reserved IP, as the VM may get a new IP on reboot.

Step 1: Sign Up#

Create a free Ametnes Platform account at https://cloud.ametnes.com. No credit card required.

Step 2: Provision the VM#

Provision an Ubuntu 20.04 LTS (or later) VM meeting the minimum specifications above. Ensure the VM can make outbound HTTPS connections to the Ametnes platform, and allow inbound HTTPS if the service endpoints will be accessed externally. Allow inbound SSH only if you will connect to the VM over SSH.

Step 3: Install K3s and the Ametnes Cloud Agent#

3.1 SSH into the VM#

ssh ubuntu@<your.vm.ip.address>

3.2 Get your Location UUID#

  1. Log in to your Ametnes Platform account
  2. Navigate to Service Locations in the left menu
  3. Copy the default location's UUID

3.3 Run the setup script#

Run the setup script as a single command, replacing <your.vm.ip.address> and <location-uuid> with your values:

curl -fsSL https://ametnes-assets.lon1.digitaloceanspaces.com/packages/setup-k3s.sh | bash -s -- --ip-address <your.vm.ip.address> --location-id <location-uuid>

Use the public IP for cloud VMs or a private IP for on-premise environments. This address is advertised as the VM's external address for service endpoints and included in the K3s TLS SAN; it is not used by the Ametnes control plane to reach the VM.

Optional: run the script as root

The setup script installs K3s system-wide and raises kernel sysctl limits, so it needs root. If your user is not root (for example a cloud VM's default ubuntu account), or you see sysctl: permission denied on key "fs.inotify.max_user_instances", ignoring, elevate the shell:

curl -fsSL https://ametnes-assets.lon1.digitaloceanspaces.com/packages/setup-k3s.sh | sudo bash -s -- --ip-address <your.vm.ip.address> --location-id <location-uuid>

Apply sudo to bash, not curl. Running sudo curl ... | bash elevates only curl and leaves the script running as your normal user, which is what produces the sysctl permission errors and prevents K3s from installing.

After a short while, the location will appear online in your Ametnes Platform console.

Step 4: Deploy a Service#

  1. Navigate to the Services dashboard using the left menu
  2. Click New Service
  3. Filter for a service (e.g., Open WebUI) and select Create
  4. Fill in the form:
  5. Name: e.g., OpenWebUI-POC
  6. Description: Optional description
  7. Version: Select a version from the list
  8. Location: Select your configured location
  9. Configure any service-specific settings
  10. Click Create

Step 5: Test Connectivity#

  1. Navigate to the Services dashboard
  2. Wait for the service status to change to ready
  3. Click the Admin button to view service details
  4. Copy the endpoint, username, and password
  5. Open the service URL in your browser and log in

Step 6: Clean Up#

When done testing, delete services from the Admin section of each service to free up resources.

Using a Production Cluster#

If you already have a Kubernetes cluster (EKS, AKS, GKE, ACK, on-premise RKE/RKE2, etc.) instead of provisioning a new VM, see Production Kubernetes Cluster Setup.