SETUP.md

Setup Guide

Prerequisites

• Go 1.25+ - Install Go
• PostgreSQL 16+ - Install PostgreSQL
• Docker & Docker Compose (optional, for containerized development)

Quick Start

Option 1: Local Development

1. Clone the repository

   git clone https://github.com/justyn-clark/go-chi-postgres-starter.git
   cd go-chi-postgres-starter

2. Install Go dependencies

   go mod tidy

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Create database

   createdb go-chi-postgres-starter
   # Or: psql -c 'CREATE DATABASE go_api_starter;'

5. Install migration tool

   go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

6. Run migrations

   export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/go_api_starter?sslmode=disable"
   make migrate-up

7. Start the server

   make run

8. Access the API

   • API: http://localhost:8080
   • Swagger UI: http://localhost:8080/swagger/index.html

Option 2: Docker Development

1. Start services

   docker compose up -d --build

2. Run migrations (first time only)

   docker compose exec api sh -c "migrate -path migrations -database \$DATABASE_URL up"

3. Access the API

   • API: http://localhost:8080
   • Swagger UI: http://localhost:8080/swagger/index.html

Generate JWT Secret

For production, generate a secure JWT secret:

openssl rand -base64 32

Add it to your .env file:

JWT_SECRET=your-generated-secret-here

Database Migrations

Create a new migration

make migrate-create NAME=add_user_table

This creates two files:

• migrations/XXXXXX_add_user_table.up.sql - Migration to apply
• migrations/XXXXXX_add_user_table.down.sql - Migration to rollback

Run migrations

make migrate-up

Rollback last migration

make migrate-down

Check migration status

make migrate-status

Generate Swagger Documentation

make swagger

This generates OpenAPI documentation from code annotations. Visit http://localhost:8080/swagger/index.html after starting the server.

Testing

# Run all tests
make test

# Run tests with coverage
make test-coverage

Production Deployment

Railway

1. Connect your GitHub repository
2. Add PostgreSQL service
3. Set environment variables:
   • DATABASE_URL (auto-provided by Railway)
   • JWT_SECRET (generate with openssl rand -base64 32)
   • ENVIRONMENT=production
4. Deploy!

Docker

# Build image
docker build -t go-chi-postgres-starter .

# Run container
docker run -p 8080:8080 \
  -e DATABASE_URL=postgresql://... \
  -e JWT_SECRET=... \
  go-chi-postgres-starter

Troubleshooting

Database connection issues

• Ensure PostgreSQL is running
• Check DATABASE_URL format: postgresql://user:password@host:port/dbname?sslmode=disable
• Verify database exists: psql -l

Migration errors

• Ensure migrations are in correct order
• Check database connection
• Verify migration files are valid SQL

Port already in use

• Change PORT in .env file
• Or stop the process using port 8080