Installation

Yew Search can currently only be installed using Docker and we specifically recommend using a docker-compose.yaml file to manage the installation.

Yew Search requires the following:

• Postgres
• Redis

You also need to install and run the Yew Search Backend and Frontend

In addition to this we recommend that you run Yew Search with Traefik

This is because Yew Search is currently designed to work behind the Traefik reverse proxy and has not been tested in other environments.

Please Note: Yew Search is still in pre-alpha. Different deployment processes are coming but are not the priority currently.

networks:
  traefik_network:
    driver: bridge

volumes:
  letsencrypt:

  postgres:
    external: true

  redis-data:
    external: true

  prometheus-data:
    external: true
  loki-data:
    external: true
  tempo-data:
    external: true
  grafana-data:
    external: true

services:
  traefik:
    image: traefik:v3.3
    container_name: traefik
    restart: unless-stopped
    command:
      - --providers.docker=true
      - --entrypoints.web.address=:80
      - --entrypoints.web.http.redirections.entryPoint.to=websecure
      - --entrypoints.web.http.redirections.entryPoint.scheme=https
      - --entrypoints.websecure.address=:443
      - --certificatesresolvers.letsencrypt.acme.tlschallenge=true
      - --certificatesresolvers.letsencrypt.acme.email=${TRAEFIK_ACME_EMAIL}
      - --certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json
    networks:
      - traefik_network
    ports:
      - "80:80"
      - "443:443"
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - letsencrypt:/letsencrypt
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.traefik-dashboard.rule=Host(`${TRAEFIK_DASHBOARD_HOST}`)"
      - "traefik.http.routers.traefik-dashboard.entrypoints=websecure"
      - "traefik.http.routers.traefik-dashboard.tls=true"
      - "traefik.http.routers.traefik-dashboard.tls.certresolver=letsencrypt"
      - "traefik.http.services.traefik-dashboard.loadbalancer.server.port=8080"

  postgres:
    image: postgres:latest
    container_name: postgres
    restart: unless-stopped
    depends_on:
      - traefik
    networks:
      - traefik_network
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}
    volumes:
      - postgres:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    labels:
      - "com.docker.stack.namespace=postgres"
      - "traefik.enable=false"

  redis:
    image: redis:latest
    container_name: redis
    restart: unless-stopped
    depends_on:
      - traefik
    networks:
      - traefik_network
    volumes:
      - redis-data:/data
    command: redis-server --requirepass ${REDIS_PASSWORD}
    ports:
      - "6379:6379"
    labels:
      - "com.docker.stack.namespace=redis"
      - "traefik.enable=false"

  yew-backend:
    # Option 1: Use latest (always get newest version on restart)
    image: registry.gitlab.com/your-namespace/yew-monorepo/backend:latest

    # Option 2: Pin to specific CalVer version (recommended for production)
    # image: registry.gitlab.com/your-namespace/yew-monorepo/backend:2025.01.27.0

    # Option 3: Use commit SHA (for debugging specific build)
    # image: registry.gitlab.com/your-namespace/yew-monorepo/backend:abc1234567

    container_name: yew-backend
    depends_on:
      - traefik
      - postgres
      - redis
    restart: unless-stopped
    networks:
      - traefik_network
    environment:
      - NODE_ENV=production
      - HTTP_PORT=8443
      - POSTGRES_HOST=${POSTGRES_HOST}
      - POSTGRES_PORT=5432
      - POSTGRES_USERNAME=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${YEW_POSTGRES_DB}
      - REDIS_HOST=${REDIS_HOST}
      - REDIS_PORT=6379
      - REDIS_PASSWORD=${REDIS_PASSWORD}
      - REDIS_DB=0
      - GOOGLE_CLIENT_ID=${GOOGLE_CLIENT_ID}
      - GOOGLE_CLIENT_SECRET=${GOOGLE_CLIENT_SECRET}
      - SESSION_DOMAIN=${SESSION_DOMAIN}
      - LOKI_URL=${LOKI_URL}
    labels:
      - "com.docker.stack.namespace=yew-search"
      - "traefik.enable=true"
      - "traefik.http.routers.yew-backend.rule=Host(`${YEW_BACKEND_HOST}`)"
      - "traefik.http.routers.yew-backend.entrypoints=websecure"
      - "traefik.http.routers.yew-backend.tls=true"
      - "traefik.http.routers.yew-backend.tls.certresolver=letsencrypt"
      - "traefik.http.services.yew-backend.loadbalancer.server.port=8443"

  yew-frontend:
    # Option 1: Use latest (always get newest version on restart)
    image: registry.gitlab.com/your-namespace/yew-monorepo/frontend:latest

    # Option 2: Pin to specific CalVer version (recommended for production)
    # image: registry.gitlab.com/your-namespace/yew-monorepo/frontend:2025.01.27.0

    # Option 3: Use commit SHA (for debugging specific build)
    # image: registry.gitlab.com/your-namespace/yew-monorepo/frontend:abc1234567

    container_name: yew-frontend
    depends_on:
      - traefik
      - yew-backend
    restart: unless-stopped
    networks:
      - traefik_network
    environment:
      - NODE_ENV=production
      - VITE_API_URL=${VITE_API_URL}
      - BACKEND_URL=${VITE_API_URL}
    labels:
      - "com.docker.stack.namespace=yew-search"
      - "traefik.enable=true"
      - "traefik.http.routers.yew-frontend.rule=Host(`${YEW_FRONTEND_HOST}`)"
      - "traefik.http.routers.yew-frontend.entrypoints=websecure"
      - "traefik.http.routers.yew-frontend.tls=true"
      - "traefik.http.routers.yew-frontend.tls.certresolver=letsencrypt"
      - "traefik.http.services.yew-frontend.loadbalancer.server.port=3000"
      - "traefik.http.middlewares.yew-frontend-headers.headers.customRequestHeaders.X-Forwarded-Proto=https"
      - "traefik.http.routers.yew-frontend.middlewares=yew-frontend-headers"

Image Versioning Strategy

Yew Search uses Calendar Versioning (CalVer) with the format YYYY.MM.DD.patch for release versions. You have three options for specifying image versions:

Option 1: Latest Tag (Development/Testing)

image: registry.gitlab.com/your-namespace/yew-monorepo/backend:latest

Use when:

• Running in development or testing environments
• You want automatic updates on container restart
• You're comfortable with potential breaking changes

Trade-off: Container will pull the newest image on restart, which may introduce unexpected changes.

Option 2: CalVer Version (Production - Recommended)

image: registry.gitlab.com/your-namespace/yew-monorepo/backend:2025.01.27.0

Use when:

• Running in production environments
• You want predictable, controlled upgrades
• You need to test updates in staging first

Benefits:

• Pin to a specific tested release
• Know exactly when the release was built
• Control when to upgrade (test in staging first)
• Easy to identify which version is running

Example versions:

• 2025.01.27.0 - First release on January 27, 2025
• 2025.01.27.1 - Hotfix/second release on same day
• 2025.02.15.0 - Release on February 15, 2025

Option 3: Commit SHA (Debugging)

image: registry.gitlab.com/your-namespace/yew-monorepo/backend:9124435e

Use when:

• Debugging a specific build
• Need exact reproducibility for troubleshooting
• Rolling back to a known-good commit

How to find: Check your GitLab/GitHub repository commit history or CI/CD pipeline logs.

Best Practices

For Production Deployments:

1. Always pin backend and frontend to the same CalVer version (e.g., both use 2025.01.27.0)
2. Test new versions in staging environment first
3. Document which version is running in production
4. Keep a rollback plan with the previous stable version number

Upgrading to a New Version:

# 1. Pull the new version
docker pull registry.gitlab.com/your-namespace/yew-monorepo/backend:2025.02.01.0

# 2. Update docker-compose.yml with new version
# 3. Restart services
docker-compose up -d yew-backend yew-frontend

# 4. Verify the deployment
docker logs yew-backend

Rolling Back:

# Update docker-compose.yml to previous version
image: registry.gitlab.com/your-namespace/yew-monorepo/backend:2025.01.27.0

# Restart
docker-compose up -d yew-backend

For more information about why Yew Search uses CalVer, see Why CalVer.