Skip to content

VM.md

Latest commit

 

History

History
124 lines (90 loc) · 4.69 KB

VM.md

File metadata and controls

124 lines (90 loc) · 4.69 KB
Raw
title Install on a VM

Install on a VM

Target: Ubuntu 22.04 / 24.04, outbound HTTPS. Installer lives in grid-core/install.

Remote state first
Create a remote Terraform state backend before applying real infra (S3, GCS, Azure, OCI, OSS, COS, or S3-compatible).
Local state on the VM is lab-only. See Remote Terraform state, then set GRID_TF_* in Compose .env / /etc/grid/grid.env.

Recommended: Compose on the VM (default)

Runs everything in Docker on that VM (core + ui). Same stack as Docker Compose.

export GRID_AUTH_ADMIN_PASSWORD='choose-a-strong-password'
# after creating remote state:
# export GRID_TF_BACKEND=s3 GRID_TF_STATE_BUCKET=… GRID_TF_LOCK_TABLE=… GRID_TF_STATE_REGION=…
curl -fsSL https://raw.githubusercontent.com/gridplatform/grid-core/main/install/install.sh | sudo -E bash

Or clone and Compose yourself:

git clone https://github.com/gridplatform/grid-core.git
cd grid-core
cp install/.env.example install/.env   # password + GRID_TF_*
docker compose -f install/docker-compose.yml --env-file install/.env up -d --build
bash install/verify.sh

Open http://<vm-ip>/.

Always running (survives SSH logout + reboot)

install.sh and the Compose examples use docker compose … up -d (detached). Closing the terminal does not stop Grid.

Layer What it does
up -d Process leaves your SSH session immediately
restart: unless-stopped on core / ui Containers restart after crash or Docker restart
systemctl enable docker Docker daemon starts on VM reboot
grid-compose.service On boot, runs compose up -d again (installed by install.sh)

Check anytime:

docker compose -f /opt/grid/grid-core/install/docker-compose.yml ps
systemctl status grid-compose docker

Do not run docker compose up without -d on a server, and do not use npm run dev for production — those die when the session ends.

Alternative: native (systemd + nginx)

No Docker. Set GRID_USE_NATIVE=1 — installs Node + Terraform, builds under /opt/grid, starts grid-core via systemd, nginx on port 80.

export GRID_USE_NATIVE=1
export GRID_AUTH_ADMIN_PASSWORD='choose-a-strong-password'
curl -fsSL https://raw.githubusercontent.com/gridplatform/grid-core/main/install/install.sh | sudo -E bash
Piece How it runs (native)
API systemd unit grid-core → node dist/index.js
CLI + Terraform On the host; core spawns them
UI Static files under /opt/grid/grid-ui/dist via nginx

Prerequisites

Need Notes
CPU / RAM 2 vCPU, 4 GB RAM minimum; 8 GB preferred
Disk ≥ 20 GB
Ports 80 (UI), Compose also uses Docker networking to core
Cloud creds On the VM / in the core container if this host will apply Terraform

Manual native steps (same end state)

sudo apt-get update
sudo apt-get install -y curl git ca-certificates build-essential nginx

# Node 24+ and Terraform ≥ 1.5 on PATH — then:
sudo mkdir -p /opt/grid && sudo chown "$USER":"$USER" /opt/grid
cd /opt/grid
git clone https://github.com/gridplatform/grid-core.git
git clone https://github.com/gridplatform/grid-cli.git
git clone https://github.com/gridplatform/grid-ui.git

cd grid-cli && npm ci && npm run build
cd ../grid-core && npm ci && npm run build
cd ../grid-ui && VITE_GRID_API_URL=/api/v1 npm ci && npm run build

Copy env from install/.env.example, install systemd/grid-core.service and nginx-host.conf, then:

sudo systemctl enable --now grid-core nginx

Configuration

See Configuration. Defaults pull desired-state from grid-config and modules from grid-terraform.

Smoke check

  1. curl -fsS http://127.0.0.1/health → {"status":"ok"}
  2. UI loads; admin login works
  3. Create a plan release for a cheap unit — confirm Releases + live logs
  4. Apply only when you accept cloud cost

Pin a release

Same script URL — change the tag (or use a channel). Full matrix: Releases.

export GRID_REF=v0.1.0
export GRID_AUTH_ADMIN_PASSWORD='…'
curl -fsSL https://raw.githubusercontent.com/gridplatform/grid-core/${GRID_REF}/install/install.sh | sudo -E bash