Docker for Finch

Finch is designed to run well inside Docker. The official uproid/finch image includes the Dart SDK, the finch CLI, and everything needed to build and serve a Finch application. The example project includes a complete docker-compose.yaml that you can use as a starting point.

Project Structure

A typical Docker-based Finch project uses these files:

my-app/
  Dockerfile            # Builds the Finch container image
  docker-compose.yaml   # Orchestrates all services
  docker/
    nginx.conf          # Nginx reverse proxy configuration
  lib/                  # Application Dart code
  public/               # Static files served by Nginx
  sqlite/               # SQLite database files (volume-mounted)

Dockerfile

The example Dockerfile uses the official Finch base image and installs dependencies at build time:

FROM uproid/finch:latest AS build
WORKDIR /www

# Environment defaults (override in docker-compose.yaml)
ENV WIDGETS_PATH=./lib/widgets
ENV WIDGETS_TYPE=j2.html
ENV LANGUAGE_PATH=./lib/languages
ENV PUBLIC_DIR=./public
ENV LOCAL_DEBUG=false
ENV ENABLE_DATABASE=true

COPY pubspec.yaml ./
RUN dart pub get --no-offline
COPY lib/ ./lib/

# Build: generates the finch app binary or pre-compiles assets
RUN finch -u

# Expose app port (8085) and live-reload port (8181)
EXPOSE 8085 8181

# On start: run the app and apply pending migrations
CMD ["finch", "serve", "-p", "/www/lib/watcher.dart", "--args=migrate --init --sqlite"]

docker-compose.yaml

The full stack includes four services: finch (your app), nginx (reverse proxy), mongodb, and optionally nodejs for frontend asset building:

services:
  finch:
    container_name: finch
    image: uproid/finch:latest
    restart: always
    ports:
      - "8085:8085"  # App port
      - "8181:8181"  # Live-reload port
    environment:
      SQLITE_PATH: /www/sqlite/example_database.sqlite
      ENABLE_DATABASE: true
      MONGODB_CONNECTION: mongodb  # Use service hostname
      MONGODB_PORT: 27017
      MONGODB_NAME: my_database
      MONGODB_AUTH: admin
      MONGODB_PASSWORD: secret
      MONGODB_USER: root
    build:
      context: .
    volumes:
      - ./lib/:/www/lib/          # Hot-reload source files
      - ./public/:/www/public/
      - ./sqlite/:/www/sqlite/    # Persist SQLite data

  nginx:
    image: nginx:latest
    container_name: nginx
    restart: always
    ports:
      - "8080:8080"  # Public-facing port
    volumes:
      - ./public/:/var/www/html/public
      - ./docker/nginx.conf:/etc/nginx/conf.d/default.conf

  mongodb:
    image: mongo:latest
    container_name: mongodb
    restart: always
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: secret
    ports:
      - "27018:27017"
    volumes:
      - mongodb_data:/data/db

volumes:
  mongodb_data:

Starting the Stack

# Build and start all services
docker-compose up --build

# Run in background (detached)
docker-compose up -d --build

# View logs
docker-compose logs -f finch

# Stop everything
docker-compose down

Once running, the app is accessible at http://localhost:8080 (via Nginx) or directly at http://localhost:8085.

Environment Variables

All FinchConfigs values that read from env[...] can be set via Docker environment variables or a .env file. The example shows the pattern:

MONGODB_CONNECTION=mongodb
MONGODB_PORT=27017
MONGODB_NAME=my_database
MONGODB_AUTH=admin
MONGODB_USER=root
MONGODB_PASSWORD=secret
ENABLE_LOCAL_DEBUGGER=false
LOCAL_DEBUG=false

See Configuration for the full list of supported environment variables.