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:

Package	Purpose
`github.com/jmoiron/sqlx`	Extended SQL operations
`github.com/lib/pq`	PostgreSQL driver
`github.com/google/uuid`	UUID generation
`github.com/robfig/cron/v3`	Cron-based scheduling
`golang.org/x/crypto`	Password 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?

Build Your First Server

Follow the Quickstart Guide to create a working HTTP server

Learn Core Concepts

Understand domains, services, and the application lifecycle

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

Get Started

Core Concepts

Guides

Installation

Installation

Prerequisites

Go 1.25+

PostgreSQL

Check Your Go Version

Install Platforma

Dependencies

Create a New Project

Basic Project Structure

Minimal Setup

Database Setup (Optional)

Using Docker

Connection String Format

Verify Installation

Development Tools (Optional)

What’s Next?

Troubleshooting

Go Version Too Old

Module Not Found

PostgreSQL Connection Issues

Ready to build?

​Installation

​Prerequisites

Go 1.25+

PostgreSQL

​Check Your Go Version

​Install Platforma

​Dependencies

​Create a New Project

​Basic Project Structure

​Minimal Setup

​Database Setup (Optional)

​Using Docker

​Connection String Format

​Verify Installation

​Development Tools (Optional)

​What’s Next?

​Troubleshooting

​Go Version Too Old

​Module Not Found

​PostgreSQL Connection Issues

Ready to build?

Installation

Prerequisites

Check Your Go Version

Install Platforma

Dependencies

Create a New Project

Basic Project Structure

Minimal Setup

Database Setup (Optional)

Using Docker

Connection String Format

Verify Installation

Development Tools (Optional)

What’s Next?

Troubleshooting

Go Version Too Old

Module Not Found

PostgreSQL Connection Issues