Skip to content

getting-started.md

Latest commit

 

History

History
195 lines (135 loc) · 5.02 KB

getting-started.md

File metadata and controls

195 lines (135 loc) · 5.02 KB

Getting Started

This guide takes you from zero to a running application in a GoShip VM.

Prerequisites

GoShip requires a Linux host with hardware virtualization support. Install the following:

# Ubuntu/Debian
sudo apt install -y \
  libvirt-dev libvirt-daemon-system \
  qemu-system-x86 qemu-utils \
  genisoimage \
  libguestfs-tools

# Verify KVM is available (recommended but not required)
ls /dev/kvm

# Add your user to the libvirt group
sudo usermod -aG libvirt $USER
# Log out and back in for the group change to take effect

# Start libvirtd
sudo systemctl enable --now libvirtd

Note: GoShip works without KVM using QEMU TCG (software emulation), but performance will be significantly degraded. See Troubleshooting — QEMU TCG Fallback for details.

You also need:

  • Go 1.26+ — to build GoShip from source
  • Docker (optional) — only needed inside VMs for container mode; GoShip installs it automatically during VM provisioning

Install GoShip

Clone and build:

git clone https://github.com/guilhermebr/goship.git
cd goship
make build

This produces two binaries in ./bin/:

  • goship — CLI tool (runs on your host)
  • goship-init — VM agent (injected into VMs automatically)

Verify the build:

./bin/goship version

You should see version info along with your libvirt and QEMU versions.

Prepare a VM Image

Download the Alpine Linux base image that GoShip uses for VMs:

./bin/goship image pull

This downloads an Alpine NoCloud QCOW2 image to ~/.goship/images/goship-vm.qcow2. The image is shared read-only — each VM gets its own copy-on-write overlay.

Create Your First Project

A project is an isolated VM where your apps will run:

./bin/goship project create myapp --cpu 1 --memory 512

This command:

  1. Creates a CoW disk overlay from the base image
  2. Provisions goship-init into the overlay using virt-customize
  3. Installs Docker inside the VM image
  4. Generates a cloud-init ISO with the VM's identity
  5. Builds libvirt domain XML and starts the VM
  6. Waits for GoShip Init to become ready

You'll see boot progress as the VM starts up. Once complete, the project is running.

Check it:

./bin/goship project list
./bin/goship project info myapp

Assign Domains (Reverse Proxy)

Assign domains to your project so the reverse proxy can route HTTP traffic to your apps:

./bin/goship domain set myapp myapp.local
./bin/goship domain list myapp

After deploying apps, they'll be accessible at {appname}.{domain}:{proxy_port} (e.g., web.myapp.local:8081).

Deploy a Container App

Create an app definition and deploy it:

# Define the app
./bin/goship app create myapp web --mode container --image nginx:alpine --port 8080:80

# Deploy it to the VM
./bin/goship app deploy myapp web

The deploy command sends the app spec to GoShip Init inside the VM, which pulls the image and starts the container.

Check Status

# List all apps in the project
./bin/goship app list myapp

# Get detailed info for a specific app
./bin/goship app info myapp web

View Logs

# App logs
./bin/goship app logs myapp web

# Follow mode (polls every 2s)
./bin/goship app logs myapp web -f

# VM-level logs (GoShip Init)
./bin/goship project logs myapp

# Cloud-init logs (provisioning)
./bin/goship project logs myapp cloud-init

Deploy a Process App

GoShip can also run plain binaries directly inside VMs, without Docker. Build a static binary and deploy it:

# Create the app definition pointing to your local binary
./bin/goship app create myapp api \
  --mode process \
  --binary ./my-server \
  --port 3000:3000 \
  --restart-policy always

# Deploy — automatically uploads the binary to the VM
./bin/goship app deploy myapp api

The binary is uploaded over virtio-serial with SHA256 verification, then started as a supervised process inside the VM.

Clean Up

# Stop and remove the app
./bin/goship app stop myapp web
./bin/goship app delete myapp web

# Delete the project and its VM
./bin/goship project delete myapp

Using the API Server

Instead of calling libvirt directly, you can run the goship server REST API server and point the CLI at it:

# Start the API server (runs on :8080 by default)
goship server &

# Point the CLI at the API server
export GOSHIP_API_URL=http://localhost:8080

# All project/app commands now go through HTTP
./bin/goship project list
./bin/goship project create myapp --cpu 1 --memory 512
./bin/goship app create myapp web --image nginx:alpine --port 8080:80
./bin/goship app deploy myapp web

This enables remote management — the CLI no longer requires libvirt on the client machine. Some commands that require direct VM access (console, project logs, push-image) are not available in API mode.

Next Steps