Quick Start#

This project comes with an executable (anar) that helps you generate and scaffold your project easily.

1. Install the anar tool#

go install codeberg.org/anarproject/anar@latest

2. Generate a new project#

anar new codeberg.org/alimiracle/blogapi
cd blogapi

This will:

• Create a new project directory named after the last part of the module path (blogapi)
• Scaffold the project structure (models/, handlers/, routes/, etc.) from the pinned anar-core template
• Initialize the Go module

3. Configure your environment#

Create a .env file in the project root. Anar first looks for .env.<APP_ENV> (.env.development by default) and falls back to .env.

# Server
SERVER_PORT=8002
APP_URL=http://localhost:8002

# JWT
JWT_SECRET=mysecret
JWT_ISSUER=anar-api

# First admin account, created on first start
ADMIN_NAME=admin
ADMIN_PASSWORD=change-me

# Database
DB_DRIVER=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=password
DB_NAME=anardb
DB_SSLMODE=disable

# Cache: memory, redis or memcached
CACHE_ENABLED=true
CACHE_TYPE=redis
CACHE_TTL=30
REDIS_ADDR=localhost:6379
REDIS_PASSWORD=

# SMTP
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=myemail@example.com
SMTP_PASSWORD=secret
SMTP_FROM=noreply@example.com

# S3 Storage
S3_ENABLED=true
S3_ENDPOINT=http://localhost:9000
S3_REGION=us-east-1
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET=anar
S3_USE_SSL=false

See the full documentation for every setting, including OAuth and logging.

4. Create your models#

You can either write models manually or generate them using the CLI.

Option A – Manual#

Open models/models.go and add a model manually. For example:

type Post struct {
    gorm.Model
    Title   string          `json:"title"`
    Content string          `json:"content"`
    Image   types.FileField `json:"image"`
}

type Comment struct {
    gorm.Model
    PostID  uint   `json:"post_id"`
    Author  string `json:"author"`
    Content string `json:"content"`
}

Option B – Generate models with the CLI#

# Generate a Post model
anar model Post title:string content:text image:string

# Generate a Comment model with relation
anar model Comment post:belongsTo author:string content:text

This adds GORM models with their fields and relationships to models/models.go. The CLI generates basic types only (string, text, int, int64, uint, float, float64, bool); to store an uploaded image, change the field to types.FileField by hand as in Option A.

5. Generate the scaffold#

anar scaffold

This generates, for every model:

• CRUD handlers in handlers/
• Migrations
• Routes in routes/generated_routes.go

Each generated handler declares its route with an //anar:route comment, so there is nothing to register by hand. For the Post model you get:

Generated routes require a valid token by default. To make one public, edit its directive (for example //anar:route GET /posts auth=public) and run anar routes. List every route with anar routes:list. See Routes for details.

6. Add your own routes (optional)#

Routes that don't come from a generated handler go in SetupRoutes in routes/roots.go, which already contains the register, login and password routes:

api.GET("/health", handler.Health) // public

7. Run the project#

Run with live reload (recommended for development). This installs air if needed and restarts the server when your code changes:

anar run

To check that the whole project compiles:

anar build

To build a binary for deployment, use the Go toolchain directly:

go build -o blogapi .
./blogapi

8. Example workflow#

# Install the anar tool
go install codeberg.org/anarproject/anar@latest

# Generate a new project
anar new codeberg.org/alimiracle/blogapi
cd blogapi

# Configure environment in .env

# Create models
anar model Post title:string content:text
anar model Comment post:belongsTo author:string content:text

# Generate handlers, migrations and routes
anar scaffold

# Run with live reload
anar run

Edit this page on Codeberg