WhoKnows is a full-stack web search engine. Users can register, log in, and search an indexed content database. The project emphasises production-grade infrastructure: containerised deployment, monitoring, and automated CI/CD.
We are using a MonoRepo project structure with 4 major folders
- /documentation
- /go_app
- /monitor
- /python_app
WhoKnows runs across two VMs:
Internet
│
┌──────▼──────┐
│ nginx │ (TLS, reverse proxy)
└──────┬──────┘
│
┌──────▼──────┐
│ Go App │ :8080
└──────┬──────┘
│
┌──────▼──────┐
│ PostgreSQL │
└─────────────┘
App VM Monitoring VM
┌─────────────────┐ ┌───────────────────────┐
│ app │ │ Prometheus :9090 │
│ nginx │◄──scrape──│ Grafana :3000 │
│ postgres │ │ Alertmanager :9093 │
│ node-exporter │ │ alertmanager-discord │
│ cAdvisor :8081 │ └───────────────────────┘
└─────────────────┘
The app VM runs the application stack. The monitoring VM scrapes metrics from node-exporter (host metrics) and cAdvisor (container metrics) on the app VM, as well as the Go app's own /metrics endpoint.
- Go — HTTP server, handlers, business logic
- PostgreSQL — primary database (users, pages)
- nginx — reverse proxy, TLS termination via Let's Encrypt
- Docker & Docker Compose — containerisation
- GitHub Actions — CI/CD pipeline
- GitHub Container Registry — image hosting (
ghcr.io/ascdevops/asc_whoknows)
- Prometheus — metrics collection and alerting rules
- Grafana — dashboards
- Alertmanager — alert routing
- Discord — alert notifications via webhook
- Playwright — end-to-end tests
- Docker and Docker Compose installed on the target VM
- A
.envfile in place (see Configuration)
# Clone the repository
git clone https://github.com/ascdevops/asc_whoknows.git
cd asc_whoknows/go_app/backend
# Copy and fill in the env file
cp .env.example .env
# Development (builds locally)
docker compose -f docker-compose.dev.yml up --build
# Production (pulls from ghcr.io)
docker compose -f docker-compose.prod.yml up -dThe app will be available at http://localhost:8080 in development.
The monitoring stack runs on a separate VM.
cd monitor
# Copy and fill in the env file
cp .env.example .env
# Start the stack
docker compose up -d| Service | Port |
|---|---|
| Prometheus | 9090 |
| Grafana | 3000 |
| Alertmanager | 9093 |
This project uses pre-commit hooks to enforce basic code hygiene and Go formatting before each commit. Lightweight checks run locally, while full linting and testing are handled in CI.
Run the following commands from the repository root.
Windows (PowerShell) — requires Python
pip install pre-commit
pre-commit installmacOS — using Homebrew
brew install pre-commit
pre-commit installTo update hooks:
pre-commit autoupdateAfter installation, hooks will automatically run on every git commit.
| Variable | Description |
|---|---|
DATABASE_URL |
PostgreSQL connection string |
POSTGRES_PASSWORD |
Password for the whoknows DB user |
ADMIN_USERNAME |
Username for the seeded admin account |
ADMIN_EMAIL |
Email for the seeded admin account |
ADMIN_PASSWORD |
Password for the seeded admin account |
| Variable | Description |
|---|---|
GRAFANA_USER |
Grafana admin username |
GRAFANA_PASSWORD |
Grafana admin password |
DISCORD_WEBHOOK |
Discord webhook URL for alert notifications |
APP_VM_IP |
IP address of the app VM (used in scrape config) |
The pipeline is defined in .github/workflows/ with the following trigger logic:
PR opened/updated → CI (build & test only)
Merge to master → CI → push to GHCR → deploy to app VM → smoke test
Each stage gates the next — a failed CI run will not produce an image, a failed push will not trigger a deploy, and a failed deploy will not run the smoke test.
Prometheus scrapes three targets on the app VM:
| Job | Target | What it covers |
|---|---|---|
whoknows-backend |
:8080/metrics |
App-level metrics |
cadvisor |
:8081 |
Docker container metrics |
node-exporter |
:9100 |
Host metrics (CPU, RAM, disk, network) |
Alert rules (defined in monitor/alertmanager/alerts.yml):
| Alert | Condition | Severity |
|---|---|---|
AppContainerDown |
App container not running > 1m | critical |
Alerts are routed through Alertmanager to a Discord channel via alertmanager-discord.
End-to-end tests are written with Playwright and located in go_app/tests/e2e/.
cd go_app
# Install dependencies
npm install
npx playwright install
# Run tests (requires the app to be running on :8080)
npx playwright testWhoKnows is not currently open for external contributions. The repository is public for presentation and reference purposes only.