Getting Started

This guide will help you set up Dockform, initialize your first project, and understand the project structure that enables automatic discovery.

Installation

Prerequisites

Before you begin, make sure you have the following installed:

• Docker with Docker Compose
• SOPS and Age (for secrets management)
• Go (optional, for building from source)

Homebrew

On macOS or Linux, install Dockform using Homebrew:

brew tap gcstr/dockform
brew install dockform

Go Install

go install github.com/gcstr/dockform@latest

Precompiled Binaries

Download binaries for Linux, macOS, and Windows from GitHub Releases.

Initialize a Project

Dockform includes a convenience command to scaffold a new project:

dockform init

This creates a starter dockform.yml manifest file.

Project Structure

Dockform v0.8 uses automatic discovery based on your directory structure. Organize your project like this:

my-project/
├── dockform.yml          # Manifest file
├── default/              # Context directory (matches Docker context name)
│   ├── web/              # Stack: default/web
│   │   ├── compose.yaml
│   │   ├── environment.env
│   │   └── volumes/
│   │       └── static/
│   │           └── index.html
│   ├── api/              # Stack: default/api
│   │   └── compose.yaml
│   └── db/               # Stack: default/db
│       └── compose.yaml

Key Conventions

Minimal Manifest

With the directory structure above, your manifest can be as simple as:

identifier: my-project

contexts:
  default: {}

Dockform automatically discovers all stacks in default/.

Quick Start Example

1. Create Project Structure

mkdir -p my-project/default/web
cd my-project

2. Create Compose File

services:
  nginx:
    image: nginx:alpine
    ports:
      - "8080:80"

3. Create Manifest

identifier: quickstart

contexts:
  default: {}

4. Preview Changes

dockform plan

Output:

│ Context: default
│ Identifier: quickstart

Stacks
  default/web
    + nginx will be created

Plan: 1 to create, 0 to change, and 0 to destroy

5. Apply

dockform apply

Your nginx container is now running at http://localhost:8080

Adding Resources

Volumes

Add volumes under your context:

identifier: my-project

contexts:
  default:
    volumes:
      app-data: {}

Reference in Compose as external:

services:
  app:
    image: myapp
    volumes:
      - app-data:/data

volumes:
  app-data:
    external: true

Networks

Add networks under your context:

identifier: my-project

contexts:
  default:
    networks:
      frontend:
        driver: bridge

Reference in Compose as external:

services:
  app:
    image: myapp
    networks:
      - frontend

networks:
  frontend:
    external: true

Filesets

Create a volumes/ directory in your stack:

default/web/
├── compose.yaml
└── volumes/
    └── config/
        └── nginx.conf

The config fileset is auto-discovered and synced to a config volume.

Stack Augmentation

Add profiles or extra environment to discovered stacks:

identifier: my-project

contexts:
  default: {}

stacks:
  default/web:
    profiles: [production]
    environment:
      inline:
        - DEBUG=false

Commands Cheatsheet

Next Steps

• The Manifest File – Full schema reference
• Stacks – Stack discovery and augmentation
• Secrets – SOPS encryption setup
• Best Practices – Production recommendations