Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Setting up SpecForge with Docker

This guide will walk you through setting up SpecForge using Docker instead of the standalone executable.

Prerequisites

Before starting the server, you must obtain and configure a valid license. If you don't have a license, please contact the SpecForge team or request a trial license.

1. Obtain the Docker Compose File

The SpecForge Server is distributed as a Docker Image via GHCR (GitHub Container Registry). The recommended way to run the Docker Image is through Docker Compose.

Download the latest docker-compose-x.y.z.yml file from the SpecForge releases page.

2. Configure Your License

The SpecForge server requires a valid license file. You need to make the license file available to the Docker container.

  1. Place your license.json file in a new directory. Using /home/user/.config/specforge/ is a common practice.

  2. Modify the following lines in your docker-compose-x.y.z.yml file to point to your license file:

    - type: bind
  source: path/to/.config/specforge/ # place your license.json file here on the host machine
  target: /app/specforgeconfig/ # config directory inside the container (do not modify this)
  read_only: true

    Note: It is not recommended to run docker as root (i.e. with sudo). But if you do, note that paths with ~/ would be understood by the system as /root/, not your home directory. So it's best to use absolute paths (without ~).

3. Configure LLM Provider (Optional)

To use LLM-based features such as natural-language spec generation and error explanation, configure an LLM provider by modifying environment variables in your docker-compose.yml file before starting the server.

For OpenAI (recommended):

- LLM_PROVIDER=openai
- LLM_MODEL=gpt-5-nano-2025-08-07
- OPENAI_API_KEY=${OPENAI_API_KEY}

Get an API key from platform.openai.com/api-keys.

You can insert API keys directly in the file, but using environment variables is better for security.

For other providers (Gemini, Ollama) and detailed configuration options, see the LLM Provider Configuration guide.

4. Start the Server

Run the following command, replacing /path/to/docker-compose-x.y.z.yml with the actual path to your downloaded file:

docker compose -f /path/to/docker-compose-x.y.z.yml up --abort-on-container-exit

The flag --abort-on-container-exit is recommended so that the container fails fast on startup errors.

You can verify that the server is up by navigating to http://localhost:8080/health, which should show version information.

Note: The server will exit immediately if the license is missing or invalid. If you encounter startup issues, verify your license configuration.

5. Install the VSCode Extension

Install the SpecForge VSCode extension from the Visual Studio Marketplace or see the VSCode Extension setup guide.

Updating the Docker Image

From time to time, new versions of the SpecForge Server are released. To use the latest version, you can either:

  1. Use the updated docker-compose file from the releases page, or

  2. Set the image field to latest in your Docker Compose file:

    image: ghcr.io/imiron-io/specforge/specforge-backend:latest

    Then pull the latest image:

    docker compose -f /path/to/docker-compose.yml pull

Next Steps