Development Setup

Prerequisites

Before you begin, ensure you have:

Go 1.25+

Download from go.dev

PostgreSQL

Running locally or accessible via connection string

Git

For version control

make (optional)

For using Makefile commands

Initial Setup

Clone the Repository

git clone https://github.com/arcten/oforum.git
cd oforum

Create Database

Create a PostgreSQL database for development:

createdb oforum

Or using psql:

CREATE DATABASE oforum;

Configure Environment

Copy the example environment file and edit if needed:

cp .env.example .env

Default .env contents:

DATABASE_URL=postgres://localhost:5432/oforum?sslmode=disable
PORT=8080

If your PostgreSQL uses different credentials, update DATABASE_URL accordingly:

postgres://username:password@host:5432/dbname?sslmode=disable

Run the Application

Migrations run automatically on startup:

go run main.go

You should see:

Migrations applied successfully
Starting server on :8080

Open in Browser

Navigate to http://localhost:8080

Create Test Admin User

You’ll need an admin account to access the admin panel.

Using Seed Data
Manual Promotion

The quickest way is to seed demo data:

go run cmd/seed/main.go

This creates:

30 users (first user “alice” is admin)
50 posts with varied content
200 comments in threaded discussions
300 upvotes distributed across content

Login credentials:

Username: alice
Password: password123

psql oforum -c "UPDATE users SET is_admin = true WHERE username = 'yourname';"

Or create an admin role and assign it:

-- Create admin role
INSERT INTO roles (name, color, sort_order, is_admin_rank) 
VALUES ('Admin', '#ef4444', 1, true);

-- Assign to user
INSERT INTO user_roles (user_id, role_id)
SELECT u.id, r.id 
FROM users u, roles r 
WHERE u.username = 'yourname' AND r.name = 'Admin';

Hot Reload Development

For faster development, use air to auto-restart the server on file changes:

Install air

go install github.com/air-verse/air@latest

Run with Hot Reload

make dev

Or directly:

air

The server will restart automatically when you edit .go, .html, or .sql files.

With air running, changes to templates and handlers take effect immediately without manual restart.

Common Development Commands

Using Make

make dev          # Start with hot reload (air)
make build        # Build binary
make release      # Cross-compile for all platforms
make seed         # Seed test data
make test         # Run tests

Manual Commands

go run main.go

Running Tests

oForum includes tests for core functionality:

# Run all tests
go test ./...

# Run with verbose output
go test -v ./...

# Run specific package tests
go test ./internal/db/

# Run tests with coverage
go test -cover ./...

Database Management

Reset Database

To start fresh during development:

# Drop and recreate
dropdb oforum
createdb oforum

# Restart server (migrations run automatically)
go run main.go

Inspect Database

# Connect to database
psql oforum

# View tables
\dt

# View schema
\d users
\d posts
\d comments

# Count records
SELECT COUNT(*) FROM posts;

Troubleshooting

”Failed to connect to database”

Ensure PostgreSQL is running:
```
pg_isready
```
Check your DATABASE_URL in .env
Verify database exists:
```
psql -l | grep oforum
```

“Migration failed”

Ensure no other instance is running
Check migration files in migrations/ are numbered sequentially
Reset the database if needed

Port Already in Use

Change the port in .env:

PORT=3000

Next Steps

Understand Architecture

Learn how the codebase is structured

Work with Database

Explore query patterns and migrations

Edit Templates

Modify the UI and template functions

Authentication Flow

Understand security and sessions

Contributing

Development Setup

Prerequisites

Go 1.25+

PostgreSQL

Git

make (optional)

Initial Setup

Create Test Admin User

Hot Reload Development

Common Development Commands

Using Make

Manual Commands

Running Tests

Database Management

Reset Database

Inspect Database

Troubleshooting

”Failed to connect to database”

“Migration failed”

Port Already in Use

Next Steps

Understand Architecture

Work with Database

Edit Templates

Authentication Flow

Build docs developers (and LLMs) love

Contributing

​Prerequisites

Go 1.25+

PostgreSQL

Git

make (optional)

​Initial Setup

​Create Test Admin User

​Hot Reload Development

​Common Development Commands

​Using Make

​Manual Commands

​Running Tests

​Database Management

​Reset Database

​Inspect Database

​Troubleshooting

​”Failed to connect to database”

​“Migration failed”

​Port Already in Use

​Next Steps

Understand Architecture

Work with Database

Edit Templates

Authentication Flow

Build docs developers (and LLMs) love

Prerequisites

Initial Setup

Create Test Admin User

Hot Reload Development

Common Development Commands

Using Make

Manual Commands

Running Tests

Database Management

Reset Database

Inspect Database

Troubleshooting

”Failed to connect to database”

“Migration failed”

Port Already in Use

Next Steps