Skip to main content

Server Deployment

Just want to run it on your laptop? See the Local Deployment Setup guide instead. This page covers running Yew Search on a real server, either your own hardware or AWS.

Yew Search is currently deployed two ways: a self-hosted homelab deployment (one Docker Compose file, everything included), and a managed AWS deployment (Terraform + ECS Fargate, used for the hosted yewsearch.com environment). Both are real, currently-used deployment paths, not just plans.

Please note: Yew Search is still pre-alpha. Deployment processes are still evolving - check this page against the actual compose files and Terraform modules linked below if anything looks out of date.

Homelab Deployment​

The portable, self-contained way to run the full stack - Postgres, Redis, Elasticsearch, backend, and frontend - on your own hardware.

cp infra/homelab/.env.example infra/homelab/.env
# edit infra/homelab/.env - at minimum, change SESSION_SECRET and
# POSTGRES_PASSWORD before exposing this deployment beyond your own machine
docker compose -f infra/homelab/docker-compose.yaml up -d

This is deliberately not the same thing as the Local Deployment guide's "Fully Offline" one-command flow (which has no Elasticsearch at all, and is meant for local development, not for actually running a homelab instance), and it is not a copy of any one person's real, personal homelab configuration either. It's meant to be the file someone with no prior Yew-specific infrastructure can bring up as-is.

See the file itself (infra/homelab/docker-compose.yaml) for the full set of comments on what each piece does and why - it's the source of truth, not this page.

Vector search is optional​

Running an embedding model is real resource cost, and this stack works with plain Elasticsearch text search alone on modest hardware (Raspberry Pi class). Vector search (Ollama) is declared behind a Compose profile and does not start by default:

docker compose -f infra/homelab/docker-compose.yaml --profile vector-search up -d
docker compose -f infra/homelab/docker-compose.yaml exec ollama ollama pull qwen3-embedding:0.6b

Then create an embedding config pointing at http://ollama:11434 and attach it to a user-integration to enable hybrid search. See the Roadmap for how the current default embedding model was chosen and why vector search is optional at all.

Putting it behind a reverse proxy​

The compose file publishes the backend and frontend on plain HTTP ports (8443 and 3000 by default). For anything beyond local access, put a reverse proxy (Traefik, Caddy, nginx) in front for TLS - that's not included in the compose file itself, since it's specific to how you're exposing the deployment (a domain you own, a VPN, a tunnel, etc.).

AWS Deployment​

The hosted yewsearch.com environment runs on AWS: ECS Fargate for the backend/frontend/website/docs containers, RDS PostgreSQL, ElastiCache Redis, an Application Load Balancer, and Route53/ACM for DNS and TLS. It's provisioned with Terraform and deployed through GitLab CI.

Full setup, teardown, cost estimates, and troubleshooting live in infra/aws/managed/README.md (that Terraform module's own README) - this page won't duplicate it, since Terraform module details drift independently of this doc.

Elasticsearch and Ollama run outside AWS​

This is the one piece of the AWS deployment that's easy to miss: Elasticsearch and Ollama are not part of the AWS infrastructure at all. The ECS-hosted backend reaches both over the internet, on the homelab, the same way any other client on the internet would - ELASTICSEARCH_HOST/ELASTICSEARCH_PORT and each embedding config's baseUrl point at homelab hostnames (e.g. elasticsearch.home.westheadjames.com:443, ollama.home.westheadjames.com) via AWS Secrets Manager, not at anything running in AWS.

This is a real architectural dependency, not a temporary gap: search and embeddings for the AWS-hosted deployment stop working if the homelab (or its internet connection) goes down, independent of whether ECS/RDS/ElastiCache are all healthy. Worth knowing before spending time debugging an AWS-side search failure that's actually a homelab connectivity issue.

Deploying a new version​

Backend, frontend, website, and docs each build and deploy through their own manual GitLab CI jobs, triggered with a CalVer VERSION_TAG (see Why CalVer). Database migrations run as their own separate, explicit CI job (manual-run-production-migration), not automatically on deploy - see infra/aws/managed/README.md for the exact job names and required inputs.

Image Versioning Strategy​

Yew Search uses Calendar Versioning (CalVer) with the format YYYY.MM.DD.patch for release versions, for both the homelab and AWS deployment paths.

Option 1: Latest Tag (Development/Testing)​

Use when you want automatic updates on container restart and are comfortable with potential breaking changes. Trade-off: pulls the newest image on restart, which may introduce unexpected changes.

Option 2: CalVer Version (Production - Recommended)​

Pin to a specific tested release, e.g. 2026.08.28.0. Know exactly when it was built, control when to upgrade, and always be able to identify which version is running.

Example versions:

  • 2026.08.28.0 - First release on August 28, 2026
  • 2026.08.28.1 - Hotfix/second release on the same day

Option 3: Commit SHA (Debugging)​

Use for debugging a specific build or rolling back to a known-good commit. Find it via GitLab CI pipeline logs.

Best Practices​

For Production Deployments:

  1. Always pin backend and frontend to the same CalVer version
  2. Test new versions somewhere other than production first
  3. Document which version is running in production
  4. Keep a rollback plan with the previous stable version number

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