Docker - tinykit

Deploy tinykit using Docker for consistent, reproducible deployments on any platform.

Quick Start

# Clone the repository
git clone https://github.com/tinykit-studio/tinykit.git
cd tinykit

# Build the image
docker build -f deploy/docker/Dockerfile -t tinykit .

# Run the container
docker run -d \
  -p 3000:3000 \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=your-api-key \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=your-password \
  -v tinykit-data:/app/pocketbase/pb_data \
  --name tinykit \
  tinykit

Access at http://localhost:3000/tinykit

Dockerfile

tinykit includes a production-ready Dockerfile:

FROM node:20-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --production=false

# Copy app
COPY . .

# Build
RUN npm run build

# Create directories for runtime
RUN mkdir -p pocketbase/pb_data workspace

# Expose port
EXPOSE 3000
ENV PORT=3000
ENV HOST=0.0.0.0

# Start
CMD ["./start.sh"]

Environment Variables

Pass environment variables with -e:

docker run -d \
  -e LLM_PROVIDER=anthropic \
  -e LLM_API_KEY=sk-ant-... \
  -e LLM_MODEL=claude-sonnet-4-20250514 \
  -e POCKETBASE_ADMIN_EMAIL=admin@example.com \
  -e POCKETBASE_ADMIN_PASSWORD=securepassword123 \
  tinykit

Or use an env file:

# Create .env.production
cat > .env.production << EOF
LLM_PROVIDER=anthropic
LLM_API_KEY=sk-ant-...
LLM_MODEL=claude-sonnet-4-20250514
POCKETBASE_ADMIN_EMAIL=admin@example.com
POCKETBASE_ADMIN_PASSWORD=securepassword123
EOF

# Run with env file
docker run -d --env-file .env.production tinykit

Data Persistence

Always use a volume for /app/pocketbase/pb_data to persist your database across container restarts.

Named Volume (Recommended)

docker run -d \
  -v tinykit-data:/app/pocketbase/pb_data \
  tinykit

Bind Mount

docker run -d \
  -v /path/on/host/pb_data:/app/pocketbase/pb_data \
  tinykit

Docker Compose

For easier management, use Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  tinykit:
    build:
      context: .
      dockerfile: deploy/docker/Dockerfile
    ports:
      - "3000:3000"
    environment:
      - LLM_PROVIDER=anthropic
      - LLM_API_KEY=${LLM_API_KEY}
      - LLM_MODEL=claude-sonnet-4-20250514
      - POCKETBASE_ADMIN_EMAIL=admin@example.com
      - POCKETBASE_ADMIN_PASSWORD=${POCKETBASE_ADMIN_PASSWORD}
    volumes:
      - tinykit-data:/app/pocketbase/pb_data
    restart: unless-stopped

volumes:
  tinykit-data:

Run with:

# Set secrets in environment or .env file
export LLM_API_KEY=sk-ant-...
export POCKETBASE_ADMIN_PASSWORD=securepassword123

# Start
docker compose up -d

# View logs
docker compose logs -f

# Stop
docker compose down

Production Deployment

With Reverse Proxy (Caddy)

# docker-compose.yml
version: '3.8'

services:
  tinykit:
    build:
      context: .
      dockerfile: deploy/docker/Dockerfile
    environment:
      - LLM_PROVIDER=anthropic
      - LLM_API_KEY=${LLM_API_KEY}
      - POCKETBASE_ADMIN_EMAIL=admin@example.com
      - POCKETBASE_ADMIN_PASSWORD=${POCKETBASE_ADMIN_PASSWORD}
    volumes:
      - tinykit-data:/app/pocketbase/pb_data
    restart: unless-stopped

  caddy:
    image: caddy:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy-data:/data
    restart: unless-stopped

volumes:
  tinykit-data:
  caddy-data:

# Caddyfile
app.yourdomain.com {
  reverse_proxy tinykit:3000
}

With nginx

# docker-compose.yml
services:
  tinykit:
    # ... same as above

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - /etc/letsencrypt:/etc/letsencrypt
    restart: unless-stopped

Health Checks

The container includes a health endpoint at /tinykit:

services:
  tinykit:
    # ...
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/tinykit"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

Updating

# Pull latest code
git pull

# Rebuild image
docker build -f deploy/docker/Dockerfile -t tinykit .

# Restart container
docker stop tinykit
docker rm tinykit
docker run -d \
  -v tinykit-data:/app/pocketbase/pb_data \
  --env-file .env.production \
  -p 3000:3000 \
  --name tinykit \
  tinykit

Or with Docker Compose:

git pull
docker compose build
docker compose up -d

Troubleshooting

Container exits immediately

Check logs with docker logs tinykit. Common issues:

Missing environment variables
Invalid API key
Port already in use

Pocketbase fails to start

Ensure the Pocketbase binary is compatible with your architecture. The default binary is for linux/amd64. For ARM (M1/M2 Mac), you may need to rebuild.

Data not persisting

Verify your volume mount:

docker inspect tinykit | grep Mounts -A 20

Ensure /app/pocketbase/pb_data is mounted to a volume.

Permission denied errors

The container runs as root by default. If using bind mounts, ensure the host directory is writable.

Resource Requirements

Resource	Minimum	Recommended
CPU	1 core	2 cores
RAM	512MB	1GB
Disk	1GB	5GB+ (depends on data)

Limit resources with Docker:

docker run -d \
  --memory="1g" \
  --cpus="1.0" \
  tinykit

​Quick Start

​Dockerfile

​Environment Variables

​Data Persistence

​Named Volume (Recommended)

​Bind Mount

​Docker Compose

​Production Deployment

​With Reverse Proxy (Caddy)

​With nginx

​Health Checks

​Updating

​Troubleshooting

​Resource Requirements

Quick Start

Dockerfile

Environment Variables

Data Persistence

Named Volume (Recommended)

Bind Mount

Docker Compose

Production Deployment

With Reverse Proxy (Caddy)

With nginx

Health Checks

Updating

Troubleshooting

Resource Requirements