school-foods-api

REST API for the school foods platform, built with Go and Gin.

Requirements

• Go 1.25+
• PostgreSQL 17+ (or Docker)

Project structure

Follows golang-standards/project-layout.

.
├── cmd/            # Application entry point
├── env/            # Environment files (gitignored, except LOCAL)
├── internal/
│   ├── config/     # Configuration loader
│   ├── handlers/   # HTTP handlers
│   ├── models/     # Database models
│   ├── routes/     # Route registration
│   └── server/     # HTTP server setup
├── pkg/
│   └── log/        # Logger
├── init.sql        # Database initialisation script
├── Dockerfile
└── compose.yml

Environment files

Environment files live in the env/ directory. The filename is the environment name in uppercase (e.g. env/LOCAL, env/DEV, env/PROD).

Variable	Description	Example
DB_HOST	PostgreSQL host	localhost
DB_PORT	PostgreSQL port	5432
DB_USER	PostgreSQL user	postgres
DB_PASSWORD	PostgreSQL password	password
DB_NAME	PostgreSQL database name	school_foods
SERVER_PORT	Port the API listens on	8080
LOG_LEVEL	Log verbosity: DEBUG, INFO, WARN, ERROR	DEBUG

Example env/LOCAL:

DB_HOST="localhost"
DB_PORT=5432
DB_USER="postgres"
DB_PASSWORD="password"
DB_NAME="school_foods"
SERVER_PORT=8080
LOG_LEVEL=DEBUG

env/ is gitignored. Create the appropriate file for each environment before running.

Running locally (without Docker)

Make sure PostgreSQL is running and reachable, then:

go run ./cmd/main.go -env=LOCAL

The -env flag is case-insensitive and defaults to local. It must match a filename inside env/.

Running with Docker Compose

Docker Compose starts both the API and a PostgreSQL container. The env file is used for both the application config and the host port mappings, so it must be passed via --env-file.

# Local
APP_ENV=LOCAL docker compose --env-file env/LOCAL up

# Dev
APP_ENV=DEV docker compose --env-file env/DEV up

# Prod
APP_ENV=PROD docker compose --env-file env/PROD up

# Run in the background
APP_ENV=LOCAL docker compose --env-file env/LOCAL up -d

When running with Docker Compose, DB_HOST in the env file is ignored — it is always overridden to db (the Postgres service name) so the API container can reach the database.

Running only the database

docker compose --env-file env/LOCAL up db

Stopping and removing volumes

# Stop containers
docker compose down

# Stop containers and delete the database volume
docker compose down -v

Database initialisation

init.sql is automatically run by PostgreSQL on the first startup (when the data volume is empty). It is idempotent — re-running it on an existing database is safe.

To force a clean reinitialisation, remove the volume first:

docker compose down -v && APP_ENV=LOCAL docker compose --env-file env/LOCAL up