Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/platforma-dev/platforma/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

Get started with Platforma by adding it to your Go project. This guide covers installation, prerequisites, and basic project setup.

​
Prerequisites

Go 1.25+

Platforma requires Go version 1.25.0 or higher

PostgreSQL

PostgreSQL database for persistence (optional for basic usage)

​
Check Your Go Version

Verify you have the correct Go version installed: 
go version
You should see output like: 
go version go1.25.0 darwin/arm64
If you need to upgrade, download the latest version from golang.org.

​
Install Platforma

Add Platforma to your project using go get: 
go get github.com/platforma-dev/platforma
This command will:
  • Download the Platforma module and its dependencies
  • Update your go.mod file with the required dependencies
  • Make all Platforma packages available for import
Platforma uses semantic versioning. Pin to a specific version in production:
go get github.com/platforma-dev/platforma@v1.2.3

​
Dependencies

Platforma brings in several carefully selected dependencies:
PackagePurpose
github.com/jmoiron/sqlxExtended SQL operations
github.com/lib/pqPostgreSQL driver
github.com/google/uuidUUID generation
github.com/robfig/cron/v3Cron-based scheduling
golang.org/x/cryptoPassword hashing
Platforma uses the lib/pq PostgreSQL driver, not pgx. If you’re migrating from another framework, you may need to adjust your database connection strings.

​
Create a New Project

Start a new Go project with Platforma: 
# Create project directory
mkdir my-platforma-app
cd my-platforma-app

# Initialize Go module
go mod init github.com/yourusername/my-platforma-app

# Install Platforma
go get github.com/platforma-dev/platforma

​
Basic Project Structure

Organize your Platforma application with this recommended structure: 
my-platforma-app/
├── cmd/
│   └── api/
│       └── main.go           # Application entry point
├── internal/
│   ├── auth/                 # Auth domain
│   │   ├── domain.go
│   │   ├── repository.go
│   │   ├── service.go
│   │   └── handlers.go
│   └── user/                 # User domain
│       ├── domain.go
│       ├── repository.go
│       └── service.go
├── migrations/               # Database migrations
│   └── 001_initial.sql
├── go.mod
└── go.sum

​
Minimal Setup

Create a minimal main.go to verify your installation:
main.go
package main

import (
	"context"
	"fmt"

	"github.com/platforma-dev/platforma/application"
)

func main() {
	ctx := context.Background()
	app := application.New()

	fmt.Println("Platforma installed successfully!")

	if err := app.Run(ctx); err != nil {
		fmt.Printf("Error: %v\n", err)
	}
}
Run it: 
go run cmd/api/main.go run
Platforma applications use a command-based CLI. You must specify a command:
  • run - Start the application services
  • migrate - Run database migrations
  • --help - Show usage information

​
Database Setup (Optional)

If your application uses a database, set up PostgreSQL:

​
Using Docker

docker run --name platforma-db \
  -e POSTGRES_PASSWORD=devpassword \
  -e POSTGRES_DB=myapp \
  -p 5432:5432 \
  -d postgres:16

​
Connection String Format

Platforma uses the lib/pq connection string format: 
connectionString := "postgres://username:password@localhost:5432/dbname?sslmode=disable"
For production, always use sslmode=require and never commit credentials to version control. Use environment variables or a secrets manager.

​
Verify Installation

Check that all dependencies are correctly installed: 
go mod tidy
go mod verify
You should see: 
all modules verified

​
Development Tools (Optional)

Platforma projects typically use Task for common operations: 
# Install Task runner (optional)
go install github.com/go-task/task/v3/cmd/task@latest

# Run linting
task lint

# Run tests
task test

# Run checks (lint + test)
task check
The Platforma repository includes a Taskfile.yml with pre-configured tasks for linting, testing, and checking code quality.

​
What’s Next?

1

Build Your First Server

Follow the Quickstart Guide to create a working HTTP server
2

Learn Core Concepts

Understand domains, services, and the application lifecycle
3

Explore Examples

Check out the demo-app in the Platforma repository

​
Troubleshooting

​
Go Version Too Old

If you see errors about Go version: 
go.mod requires go >= 1.25, but go is version 1.22
Upgrade Go to version 1.25 or higher.

​
Module Not Found

If imports fail: 
go mod tidy
go clean -modcache
go get github.com/platforma-dev/platforma

​
PostgreSQL Connection Issues

Verify your database is running and accessible: 
psql -h localhost -U username -d dbname

Ready to build?

Create your first Platforma HTTP server

Build docs developers (and LLMs) love

Get started for freeTalk to us