Local setup

This guide walks you through setting up the Address API on your local machine for development.

Prerequisites

Before you begin, ensure you have the following installed:

Tool	Required version	Check command
Go	1.23.1 or higher	`go version`
PostgreSQL	15 or higher	`psql --version`
Docker	Latest	`docker --version`
Git	Latest	`git --version`
Atlas	Latest	`atlas version`
sqlc	Latest	`sqlc version`

Step 1: Clone the repository

git clone https://github.com/commenda-eng/address-api.git
cd address-api

Step 2: Install PostgreSQL

macOS (using Homebrew)

brew install postgresql@15
brew services start postgresql@15

Ubuntu/Debian

sudo apt update
sudo apt install postgresql-15 postgresql-contrib-15
sudo systemctl start postgresql
sudo systemctl enable postgresql

Windows

Download and install from PostgreSQL official website.

Verify installation

psql --version
# Should output: psql (PostgreSQL) 15.x

Step 3: Create database

# Connect to PostgreSQL
psql postgres

# Create database
CREATE DATABASE address_api_dev;

# Create user (optional)
CREATE USER address_api_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE address_api_dev TO address_api_user;

# Exit
\q

Step 4: Set up environment variables

Create a .env file in the project root:

cp .env.test.example .env

Edit .env with your configuration:

# Server configuration
PORT=8080

# Database configuration
RDS_USERNAME=postgres
RDS_PASSWORD=your_password
RDS_HOSTNAME=localhost
RDS_PORT=5432
RDS_DBNAME=address_api_dev
DATABASE_URL=postgresql://postgres:your_password@localhost:5432/address_api_dev?sslmode=disable

# Google Geocoding API key (required for geocoding)
GOOGLE_GEOCODING_API_KEY=your_google_api_key_here

Getting a Google Geocoding API key

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Geocoding API
Go to Credentials → Create Credentials → API Key
Copy the API key and add it to your .env file

Step 5: Install development tools

Install Atlas

# macOS
brew install ariga/tap/atlas

# Linux
curl -sSf https://atlasgo.sh | sh

# Windows
# Download from https://atlasgo.io/getting-started#installation

Install sqlc

# macOS
brew install sqlc

# Linux/Windows
# Download from https://docs.sqlc.dev/en/latest/overview/install.html

Install Lefthook (Git hooks)

# macOS
brew install lefthook

# Linux/Windows
go install github.com/evilmartians/lefthook@latest

Then install the hooks:

lefthook install

Step 6: Make scripts executable

# Option 1: Use the Makefile
make prepare

# Option 2: Use make start (which calls prepare)
make start

This makes all shell scripts in the scripts/ directory executable.

Step 7: Run database migrations

Apply all migrations using the provided script:

./scripts/apply.sh

The script reads DATABASE_URL from your .env file. Alternatively, pass the URL directly:

./scripts/apply.sh --url "postgresql://postgres:your_password@localhost:5432/address_api_dev?sslmode=disable"

Verify migrations

# Connect to database
psql -U postgres -d address_api_dev

# List tables
\dt

# Should see:
# - iso_3166
# - address_cache
# - api_key
# - atlas_schema_revisions

# Exit
\q

Step 8: Generate database code

The project uses sqlc to generate type-safe Go code from SQL queries.

sqlc generate

This generates Go code in database/generated_models/.

Step 9: Install Go dependencies

go mod download
go mod tidy

Step 10: Start the server

go run main.go serve

You should see:

{"level":"info","port":"8080","time":1734518400,"message":"server started"}

Step 11: Verify the server is running

Test root endpoint

curl http://localhost:8080/
# Output: Commenda address validation API is up and running.

Test health endpoint

curl http://localhost:8080/healthz

Expected response:

{
  "api": true,
  "database_pool": {
    "total_connections": 12,
    "acquired_connections": 0,
    "idle_connections": 12,
    "max_connections": 48,
    "acquire_duration_ms": 2
  }
}

Step 12: Create an API key for testing

Connect to the database and insert a test API key:

psql -U postgres -d address_api_dev

INSERT INTO api_key (key, organization_name, roles)
VALUES ('test-api-key-local', 'Local Development', ARRAY['GEOCODE', 'MANAGE_CONTENT']);

Step 13: Test the geocoding endpoint

curl -X POST http://localhost:8080/api/v1/geoencode \
  -H "x-commenda-key: test-api-key-local" \
  -H "Content-Type: application/json" \
  -d '{"address": "94108, CA, US"}'

If successful, you’ll receive a geocoded response with address components and coordinates.

Troubleshooting

Error: “could not ping the database”

Cause: PostgreSQL is not running or connection details are incorrect. Fix:

# Check if PostgreSQL is running
pg_isready

# Start PostgreSQL
# macOS
brew services start postgresql@15

# Linux
sudo systemctl start postgresql

Error: “missing required environment variables”

Cause: .env file is missing or incomplete. Fix: Ensure all required variables are set in .env:

RDS_USERNAME
RDS_PASSWORD
RDS_HOSTNAME
RDS_PORT
RDS_DBNAME

Error: “GOOGLE_GEOCODING_API_KEY is required”

Cause: Google API key is not set or invalid. Fix:

Get a valid API key from Google Cloud Console
Add it to .env file
Restart the server

Error: “relation does not exist”

Cause: Database migrations haven’t been applied. Fix:

./scripts/apply.sh

Error: “permission denied” when running scripts

Cause: Scripts are not executable. Fix:

make prepare

CommendaOS

Indirect Tax

Workflow Builder

Form Builder

Address API

Prerequisites

Step 1: Clone the repository

Step 2: Install PostgreSQL

macOS (using Homebrew)

Ubuntu/Debian

Windows

Verify installation

Step 3: Create database

Step 4: Set up environment variables

Getting a Google Geocoding API key

Step 5: Install development tools

Install Atlas

Install sqlc

Install Lefthook (Git hooks)

Step 6: Make scripts executable

Step 7: Run database migrations

Verify migrations

Step 8: Generate database code

Step 9: Install Go dependencies

Step 10: Start the server

Step 11: Verify the server is running

Test root endpoint

Test health endpoint

Step 12: Create an API key for testing

Step 13: Test the geocoding endpoint

Troubleshooting

Error: “could not ping the database”

Error: “missing required environment variables”

Error: “GOOGLE_GEOCODING_API_KEY is required”

Error: “relation does not exist”

Error: “permission denied” when running scripts

Next steps

CommendaOS

Indirect Tax

Workflow Builder

Form Builder

Address API

​Prerequisites

​Step 1: Clone the repository

​Step 2: Install PostgreSQL

​macOS (using Homebrew)

​Ubuntu/Debian

​Windows

​Verify installation

​Step 3: Create database

​Step 4: Set up environment variables

​Getting a Google Geocoding API key

​Step 5: Install development tools

​Install Atlas

​Install sqlc

​Install Lefthook (Git hooks)

​Step 6: Make scripts executable

​Step 7: Run database migrations

​Verify migrations

​Step 8: Generate database code

​Step 9: Install Go dependencies

​Step 10: Start the server

​Step 11: Verify the server is running

​Test root endpoint

​Test health endpoint

​Step 12: Create an API key for testing

​Step 13: Test the geocoding endpoint

​Troubleshooting

​Error: “could not ping the database”

​Error: “missing required environment variables”

​Error: “GOOGLE_GEOCODING_API_KEY is required”

​Error: “relation does not exist”

​Error: “permission denied” when running scripts

​Next steps

Prerequisites

Step 1: Clone the repository

Step 2: Install PostgreSQL

macOS (using Homebrew)

Ubuntu/Debian

Windows

Verify installation

Step 3: Create database

Step 4: Set up environment variables

Getting a Google Geocoding API key

Step 5: Install development tools

Install Atlas

Install sqlc

Install Lefthook (Git hooks)

Step 6: Make scripts executable

Step 7: Run database migrations

Verify migrations

Step 8: Generate database code

Step 9: Install Go dependencies

Step 10: Start the server

Step 11: Verify the server is running

Test root endpoint

Test health endpoint

Step 12: Create an API key for testing

Step 13: Test the geocoding endpoint

Troubleshooting

Error: “could not ping the database”

Error: “missing required environment variables”

Error: “GOOGLE_GEOCODING_API_KEY is required”

Error: “relation does not exist”

Error: “permission denied” when running scripts

Next steps