Documentation/Stack/

Getting Started with Stack

Getting Started with Stack

This guide walks you through defining services, starting them, and managing them with the 8v CLI. By the end, you'll have a running database and know how to check its status, read its logs, and shut it down.

Prerequisites

  • 8Vast installed and the daemon running (8v daemon status should show it active)
  • A project initialized (8v project init in your project directory)

Create a stack definition

8Vast reads stack definitions from .8v/stack.yaml inside your project directory. Create the file:

services:
  database:
    image: postgres:15
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: dev
    healthcheck:
      test: "pg_isready"
      interval: 10s

This defines one service called database. It uses the postgres:15 image, forwards port 5432 to your machine, sets an environment variable, and runs pg_isready every 10 seconds to check health.

Start the service

8v stack up

8Vast pulls the image (if not already cached), boots the service, sets up port forwarding, and streams logs to your terminal. You'll see the database starting up and accepting connections.

Press Ctrl+C to stop everything.

Run in the background

If you don't want logs in your terminal, start in detached mode:

8v stack up -d

The services start in the background. The daemon manages their lifecycle — health monitoring, automatic restarts, log collection. You get your terminal back immediately.

Check status

8v stack status

This shows each service with its current state, resource usage, IP address, and health:

Name             Image                    CPU    Mem Status     IP               Health
-----------------------------------------------------------------------------------------------
database         postgres:15                1    512 running    192.168.64.5     healthy

View logs

8v stack logs database

Shows the last 100 lines of output from the database service. To follow logs in real time:

8v stack logs database -f

To show more or fewer lines:

8v stack logs database --tail 50

Stop everything

8v stack down

All services stop and their resources are released.

Multiple services

Most projects need more than one service. Here's a stack with a database, an API server, and a cache:

services:
  database:
    image: postgres:15
    ports:
      - "5432:5432"
    environment:
      POSTGRES_PASSWORD: dev
    healthcheck:
      test: "pg_isready"
      interval: 10s

  api:
    image: myrepo/api:latest
    ports:
      - "8080:8080"
    depends_on:
      - database
    environment:
      DATABASE_URL: postgres://postgres:dev@database:5432/app

  redis:
    image: redis:7
    ports:
      - "6379:6379"
    healthcheck:
      test: "redis-cli ping"
      interval: 10s

When you run 8v stack up, services start in dependency order. database and redis start first (they have no dependencies). api waits for database to be healthy before starting — not just running, but passing its health check.

Services on the same stack can reach each other by name. The api service connects to database using database as the hostname in its connection string.

Start specific services

You don't have to start everything. To start only the database:

8v stack up database

To start only the database and redis:

8v stack up database redis

Dependencies are respected — if you start api, its dependency database starts too.

Run a command inside a service

To open a shell inside a running service:

8v stack exec database

This drops you into /bin/sh inside the service. To run a specific command:

8v stack exec database -- psql -U postgres

Validate your configuration

Before starting, you can check your stack definition for errors:

8v stack validate

This catches problems like missing images, port conflicts, undefined dependencies, and circular dependency chains — before anything starts.

Split file format

For larger stacks, you can split the definition into separate files instead of one stack.yaml. Create a .8v/stack/ directory:

.8v/stack/
  defaults.yaml          # Stack-wide defaults (cpus, memory)
  services/
    database.yaml        # One file per service
    api.yaml
    redis.yaml
  networks/
    frontend.yaml        # One file per network

8Vast checks for the directory first. If it exists, it loads from there. Otherwise, it falls back to .8v/stack.yaml.

Next

Referenced by