MosaicπŸ“”

Server Development

How to set up and run the Mosaic Go server locally for development

Server Development

The Mosaic production server is built with Go using chi, pgx, and goose. This guide covers local development setup.

Looking for the Rust tree? It lives in server/ as a reference implementation and is not the deployed backend.

Prerequisites

  • Go 1.26+
  • PostgreSQL 15+ with pgvector extension
  • FFmpeg (optional, for video processing)

Setup

1. Clone and enter the server directory

git clone https://github.com/crayonlu/Mosaic
cd Mosaic/server-go

2. Configure environment

cp .env.example .env
# Edit .env with your database credentials

3. Set up the database

Create a PostgreSQL database:

createdb mosaic
# or
psql -c "CREATE DATABASE mosaic;"

Enable the pgvector extension:

psql -d mosaic -c "CREATE EXTENSION IF NOT EXISTS vector;"

4. Run the server

go run ./cmd/mosaic-server

The server will:

  1. Read configuration from .env
  2. Connect to PostgreSQL
  3. Apply pending migrations through goose
  4. Start listening on the configured port (default: 8080)

Project Structure

server-go/
β”œβ”€β”€ cmd/
β”‚   β”œβ”€β”€ mosaic-server/     # Entry point
β”‚   └── baseline-sqlx/     # One-time migration bookkeeping
β”œβ”€β”€ internal/
β”‚   β”œβ”€β”€ config/      # Environment configuration
β”‚   β”œβ”€β”€ httpapi/     # Routing, handlers, middleware
β”‚   β”œβ”€β”€ service/     # Business logic
β”‚   β”œβ”€β”€ store/       # PostgreSQL access
β”‚   β”œβ”€β”€ domain/      # Types and shared contracts
β”‚   β”œβ”€β”€ adapters/    # AI and external integrations
β”‚   β”œβ”€β”€ auth/        # JWT and password hashing
β”‚   β”œβ”€β”€ media/       # Image and video processing
β”‚   └── storage/     # File storage (local/S3)
β”œβ”€β”€ migrations/      # SQL migration files
β”œβ”€β”€ third-party/     # Bundled licenses
β”œβ”€β”€ Dockerfile
└── .env.example

Key Dependencies

PackagePurpose
chiHTTP router
pgxPostgreSQL driver and connection pool
gooseMigration runner
golang-jwtJWT authentication
golang.org/x/cryptoPassword hashing
pgvectorVector embeddings for semantic search

Common Commands

go run ./cmd/mosaic-server   # Start the server
go build ./...               # Build all packages
go test ./...                # Run tests
go vet ./...                 # Static checks

Database Migrations

Migrations live in server-go/migrations/ (just migrations/ once you are in that directory) and run automatically on startup via goose. Each migration is a timestamped SQL file that must start with a -- +goose Up directive; a -- +goose Down section is optional. The applied set is recorded in the goose_db_version table. To add a new migration:

touch migrations/$(date -u +"%Y%m%d%H%M%S")_your_description.sql

Write the -- +goose Up SQL in the file. On the next server restart, it is applied automatically. The Go tree mirrors the Rust tree's migrations and adds the goose directives; the SQL bodies are the same.

Server

Mosaic Go backend overview

Server Deployment

Deploying the Mosaic server

On this page

Server DevelopmentPrerequisitesSetup1. Clone and enter the server directory2. Configure environment3. Set up the database4. Run the serverProject StructureKey DependenciesCommon CommandsDatabase Migrations