From Source

Build and run Authority from source code.

Prerequisites

• Crystal 1.9+

• PostgreSQL 13+

• Git

Step 1: Clone Repository

git clone https://github.com/azutoolkit/authority.git
cd authority

Step 2: Install Dependencies

shards install

Step 3: Set Up Database

Create the database:

createdb authority_db

Or using psql:

psql -c "CREATE DATABASE authority_db;"

Step 4: Configure Environment

Copy the example environment file:

cp .env.example .env.local

Edit .env.local:

# Server
CRYSTAL_ENV=development
PORT=4000
BASE_URL=http://localhost:4000

# Database
DATABASE_URL=postgres://localhost:5432/authority_db

# Security
SECRET_KEY=development-secret-key-change-in-production

# Token Lifetimes
ACCESS_TOKEN_TTL=3600
CODE_TTL=600

Step 5: Run Migrations

crystal run src/db/migrate.cr

Step 6: Seed Default Data (Optional)

Create an admin user:

crystal run src/db/seed.cr

Step 7: Start the Server

Development mode:

crystal run src/app.cr

Or with hot reload:

./scripts/dev.sh

Production Build

Compile Release Binary

crystal build src/app.cr --release -o bin/authority

Run Production Server

CRYSTAL_ENV=production ./bin/authority

Running Tests

crystal spec

Run specific tests:

crystal spec spec/models/user_spec.cr

Development Workflow

Watch for Changes

Use watchexec or similar:

watchexec -e cr -r "crystal run src/app.cr"

Database Reset

dropdb authority_db
createdb authority_db
crystal run src/db/migrate.cr
crystal run src/db/seed.cr

File Structure

authority/
├── src/
│   ├── app.cr              # Application entry point
│   ├── db/
│   │   ├── migrate.cr      # Migration runner
│   │   ├── seed.cr         # Seed data
│   │   └── migrations/     # Migration files
│   ├── endpoints/          # HTTP handlers
│   ├── models/             # Data models
│   ├── services/           # Business logic
│   └── views/              # Response serializers
├── public/
│   ├── templates/          # Jinja templates
│   ├── css/                # Stylesheets
│   └── js/                 # JavaScript
├── spec/                   # Tests
├── shard.yml               # Dependencies
└── .env.example            # Environment template

Common Issues

Crystal not found

Ensure Crystal is in your PATH:

export PATH="$PATH:/usr/local/crystal/bin"

PostgreSQL connection refused

Start PostgreSQL:

# macOS
brew services start postgresql

# Linux
sudo systemctl start postgresql

Shards install fails

Update shards cache:

rm -rf lib .shards
shards install

Port already in use

Check what's using the port:

lsof -i :4000

Next Steps

• Docker Installation - Containerized deployment

• Database Setup - Database configuration

• Environment Variables - All settings