Running services

Run the API server and background worker services in development

Overview

Boiler-Go consists of two main services:

• API Server: Handles HTTP requests and serves the REST API
• Worker: Processes background jobs using Asynq

Both services can run independently and connect to the same PostgreSQL and Redis instances.

Prerequisites

Before running the services, ensure you have:

1. Started development services

   PostgreSQL and Redis must be running:

   make dev
   
2. Applied database migrations

   Your database schema must be up to date:

   make migrate-up
   
3. Configured environment variables

   Your .env file should be properly configured. See Development setup for details.

Running the API server

Start the API server using the Makefile command:

make api

This runs go run ./cmd/api and starts the HTTP server on the port specified in your .env file (default: 8080).

Verify the API is running

Test the health check endpoint:

curl http://localhost:8080/health

You should receive a successful response indicating the API is running and database connectivity is working.

API logs

The API server logs all requests and errors based on your LOG_OUTPUT configuration:

• stdout: Logs appear in your terminal
• file: Logs are written to the path specified in LOG_FILE
• both: Logs appear in both terminal and file

Running the worker

Start the background worker in a separate terminal:

make worker

This runs go run ./cmd/worker and starts processing jobs from the Redis queue.

Worker functionality

The worker service:

• Connects to Redis using the REDIS_ADDR configuration
• Processes background jobs asynchronously
• Handles retries and error logging
• Supports graceful shutdown with WORKER_SHUTDOWN_TIMEOUT

Running both services simultaneously

For a complete development environment, run both services in separate terminal windows:

Terminal 1 - API Server

make api

Alternatively, you can use a process manager like air for hot reloading during development.

Stopping services

Stop API or Worker

Press Ctrl+C in the terminal where the service is running. The service will gracefully shut down, waiting for ongoing requests or jobs to complete within the configured timeout.

Stop development services

To stop PostgreSQL and Redis:

make dev-down

This stops and removes the Docker containers but preserves data in Docker volumes.

Troubleshooting

Connection refused errors

Ensure PostgreSQL and Redis are running:

docker ps

If containers aren’t running, start them with make dev.

Port already in use

If port 8080 is already in use, change the APP_PORT in your .env file:

APP_PORT=3000

Database migration errors

Ensure migrations are up to date:

make migrate-up

See Database migrations for more details.

Environment variables not loaded

Verify your .env file exists in the project root and contains all required variables from .env.example.

Next steps

• Learn about Database migrations
• Run the Testing suite
• Deploy your application with the Deployment guide