Book API

A production-like REST API infrastructure built with Go and PostgreSQL, featuring Docker, Nginx, CI/CD, monitoring, centralized logging, and alerting.

Architecture

                         ┌───────────────┐
                         │    Internet   │
                         └───────┬───────┘
                                 │
                                 ▼
                         ┌───────────────┐
                         │     Nginx     │
                         └───────┬───────┘
                                 │
                                 ▼
                         ┌───────────────┐
                         │    Book API   │
                         │      Go       │
                         └───────┬───────┘
                                 │
                                 ▼
                         ┌───────────────┐
                         │  PostgreSQL   │
                         └───────────────┘

        ┌─────────────────────────────────────────┐
        │              Reliability                │
        │                                         │
        │ PostgreSQL ──► Backup / Restore         │
        │ Docker ──────► Health Checks            │
        │ Go API ──────► Graceful Shutdown        │
        └─────────────────────────────────────────┘

        ┌─────────────────────────────────────────┐
        │              Observability              │
        │                                         │
        │ Prometheus ──► Grafana                  │
        │ Node Exporter ─► Grafana                │
        │ Promtail ──► Loki ──► Grafana           │
        │ Prometheus ──► Alertmanager              │
        └─────────────────────────────────────────┘

Project Goal

This repository demonstrates the evolution of a backend service into a production-like infrastructure.

The project gradually grows from a simple REST API into a reliable, observable, and automated platform featuring monitoring, centralized logging, infrastructure automation, Kubernetes, and GitOps.

Roadmap

v1.0 — Foundation

• REST API
• PostgreSQL
• Docker
• Docker Compose
• Nginx
• HTTPS
• CI/CD

v2.0 — Observability

• Prometheus
• Application metrics
• Grafana
• Application dashboard
• Server dashboard
• Node Exporter
• Loki
• Promtail
• Alertmanager
• Alert rules
• Grafana provisioning

v3.0 — Reliability

• Automated PostgreSQL Backup
• PostgreSQL Restore
• Health Checks
• Graceful Shutdown
• Failure Tests

v4.0 — Automation

• Ansible
• Infrastructure automation

v5.0 — Kubernetes

• k3s
• Helm
• Ingress
• Cert-Manager
• Readiness / Liveness Probes
• Rolling Updates
• HPA
• Persistent Volumes

v6.0 — GitOps

• ArgoCD
• Canary
• Rollback

Tech Stack

Application

• Go
• PostgreSQL

Infrastructure

• Docker
• Docker Compose
• Nginx
• Ansible

Observability

• Prometheus
• Grafana
• Node Exporter
• Loki
• Promtail
• Alertmanager

Reliability

• PostgreSQL Backup / Restore
• Docker Health Checks
• Graceful Shutdown

Monitoring

The application exposes Prometheus metrics through:

/metrics

Application metrics include:

• HTTP requests
• HTTP errors
• HTTP request duration
• Books created
• Books returned
• Database queries

Grafana provides separate dashboards for:

• Application
• Server

Loki and Promtail provide centralized collection and visualization of Docker container logs.

Alertmanager handles alerts generated by Prometheus.

Reliability

The project includes reliability mechanisms for backup, service health monitoring, and graceful application shutdown.

Backup / Restore

PostgreSQL backups are created automatically using pg_dump and scheduled with cron.

Backups can be restored to a separate PostgreSQL database for verification.

Health Checks

Docker health checks are configured for the application and infrastructure services.

The Go API exposes:

/health

Graceful Shutdown

The Go HTTP server handles SIGTERM and SIGINT signals.

During shutdown:

1. New HTTP requests are no longer accepted.
2. Active requests are allowed to finish.
3. PostgreSQL connections are closed.
4. The application process exits.

Prerequisites

• Docker
• Docker Compose

Getting Started

1. Clone the repository.

2. Copy the environment template:

cp .env.example .env

3. Start the application:

docker compose up --build

The API will be available at:

http://localhost

Grafana:

http://localhost:3000

Prometheus:

http://localhost:9090

Alertmanager:

http://localhost:9093

Environment Variables

The project uses the following environment variables:

Variable	Description
DB_HOST	PostgreSQL host
DB_PORT	PostgreSQL port
DB_USER	PostgreSQL username
DB_PASSWORD	PostgreSQL password
DB_NAME	PostgreSQL database name

See .env.example for default values.

Infrastructure Automation

The project uses Ansible to automate VPS provisioning and application deployment.

What Ansible does

The playbook (ansible/playbook.yml) performs the following on a fresh Ubuntu server:

1. Installs system dependencies (ca-certificates, curl, git).
2. Installs Docker Engine and Docker Compose plugin.
3. Creates a deploy user with Docker access.
4. Adds your SSH public key for the deploy user.
5. Clones the repository from GitHub.
6. Generates the .env file from a Jinja2 template.
7. Pulls the latest Docker images.
8. Starts the application stack with docker compose up -d.

Usage

# Edit ansible/vars.yml to set your SSH key and DB credentials
# Then run:
ansible-playbook -i ansible/inventory.ini ansible/playbook.yml

The inventory targets a single production host (prod) at 104.252.127.239.

Project Structure

.
├── alertmanager/
│   └── alertmanager.yml
├── ansible/
│   ├── inventory.ini
│   ├── playbook.yml
│   ├── templates/
│   │   └── .env.j2
│   └── vars.yml
├── db/
│   └── init.sql
├── grafana/
│   └── provisioning/
│       ├── dashboards/
│       └── datasources/
├── loki/
│   └── loki-config.yml
├── nginx/
│   └── nginx.conf
├── prometheus/
│   ├── prometheus.yml
│   └── alerts.yml
├── promtail/
│   └── promtail-config.yml
├── docker-compose.yml
├── Dockerfile
├── main.go
└── README.md