Installation

This guide covers the complete installation process for POS Kasir, including prerequisites, setup options, and verification steps.

System Requirements

Backend Requirements

Go: Version 1.22 or higher
PostgreSQL: 12 or higher
golang-migrate: For database migrations
sqlc: For type-safe SQL code generation (development only)

Frontend Requirements

Bun: Version 1.0 or higher
Node.js: Compatible with Bun runtime

Infrastructure

Docker: 20.10 or higher
Docker Compose: v2.0 or higher

Installation Methods

Docker (Recommended)
Manual Installation
Development Setup

Docker Installation

Docker is the recommended method for running POS Kasir, as it handles all dependencies automatically.

Clone Repository

git clone https://github.com/agpprastyo/POS-kasir.git
cd POS-kasir

Setup Environment

cp .env.example .env
cp web/.env.example web/.env

Edit .env with your configuration. See Configuration for details.

Start Services

docker-compose up -d

This command:

Builds backend and frontend images
Creates a dedicated network
Starts services with resource limits
Enables automatic restarts

Initialize Database

make migrate-up
make seed

Verify Installation

Check if all services are running:

docker-compose ps

You should see both pos-backend and pos-frontend containers running.

Docker Resource Limits

The default docker-compose.yml sets resource limits:

deploy:
  resources:
    limits:
      cpus: '0.50'
      memory: 512M

Adjust these limits based on your system resources and load requirements.

Manual Installation

For development or when Docker is not available, you can install manually.

Install Go

Download and install Go 1.22+ from go.devVerify installation:

go version

Install Bun

Install Bun runtime:

curl -fsSL https://bun.sh/install | bash

Verify installation:

bun --version

Install PostgreSQL

Install PostgreSQL 12+ using your system’s package manager or download from postgresql.orgCreate a database:

createdb pos_kasir

Clone Repository

git clone https://github.com/agpprastyo/POS-kasir.git
cd POS-kasir

Configure Environment

cp .env.example .env

Update database connection in .env:

DB_HOST=localhost
DB_PORT=5432
DB_USER=your_user
DB_PASSWORD=your_password
DB_NAME=pos_kasir

Install Backend Dependencies

go mod download

Run Migrations

Install golang-migrate:

brew install golang-migrate

Run migrations:

make migrate-up

Seed Database

make seed

Start Backend

go run cmd/app/main.go

The API will be available at http://localhost:8080

Install Frontend Dependencies

cd web
bun install

Configure Frontend

cp .env.example .env

Update API endpoint:

VITE_API_BASE=http://localhost:8080/api/v1

Start Frontend

bun run dev

The frontend will be available at http://localhost:3000

Development Environment

For active development with hot-reloading.

Install Development Tools

Install additional development dependencies:

# Install air for hot-reloading
go install github.com/cosmtrek/air@latest

# Install sqlc for code generation
go install github.com/sqlc-dev/sqlc/cmd/sqlc@latest

# Install swag for API docs generation
go install github.com/swaggo/swag/cmd/swag@latest

Setup Database

Run PostgreSQL with Docker for development:

docker run -d \
  --name pos-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pos_kasir \
  -p 5432:5432 \
  postgres:15-alpine

Run Migrations and Seed

make migrate-up
make seed

Start Backend with Hot-Reload

If you have Air configured:

air

Otherwise:

go run cmd/app/main.go

Start Frontend with Hot-Reload

cd web
bun run dev

Generate Code

When you modify SQL queries or API endpoints:

# Generate sqlc code
make sqlc-generate

# Generate Swagger docs
make swag

Makefile Commands

POS Kasir includes a Makefile for common operations:

Command	Description
`make migrate-up`	Apply all pending migrations
`make migrate-down`	Rollback all migrations
`make migrate-down-one`	Rollback last migration
`make migrate-version`	Show current migration version
`make migrate-create name=<name>`	Create new migration file
`make seed`	Run database seeders
`make sqlc-generate`	Generate sqlc code
`make swag`	Generate Swagger documentation
`make docker-be`	Build and start backend Docker container
`make docker-be-down`	Stop backend Docker container

Verification

After installation, verify everything is working:

Check Backend Health

curl http://localhost:8080/api/v1/health

Or visit the Swagger UI:

http://localhost:8080/swagger/index.html

Check Frontend

Open your browser and navigate to:

http://localhost:3000

You should see the login page.

Test Login

Check Database Connection

make migrate-version

This should display the current migration version without errors.

Troubleshooting

If you encounter issues during installation, check the following:

Common Issues

Go Module Download Fails

If go mod download fails, ensure you have proper internet connectivity and Go is properly configured:

go env GOPROXY

You may need to configure a proxy:

go env -w GOPROXY=https://proxy.golang.org,direct

Migration Fails

If migrations fail with “dirty” state:

# Check current version
make migrate-version

# Force to specific version
make migrate-force version=1

# Then try again
make migrate-up

Port Conflicts

If ports 3000 or 8080 are already in use:

# Find process using port
lsof -i :8080

# Kill process or change port in .env
APP_PORT=8081

Docker Build Fails

Clear Docker cache and rebuild:

docker-compose down
docker system prune -a
docker-compose up -d --build

Overview

Getting Started

Core Features

Integrations

Deployment

Development

System Requirements

Backend Requirements

Frontend Requirements

Infrastructure

Installation Methods

Docker Installation

Docker Resource Limits

Manual Installation

Development Environment

Makefile Commands

Verification

Troubleshooting

Common Issues

Next Steps

Configuration

First Steps

Build docs developers (and LLMs) love

Overview

Getting Started

Core Features

Integrations

Deployment

Development

​System Requirements

​Backend Requirements

​Frontend Requirements

​Infrastructure

​Installation Methods

​Docker Installation

​Docker Resource Limits

​Manual Installation

​Development Environment

​Makefile Commands

​Verification

​Troubleshooting

​Common Issues

​Next Steps

Configuration

First Steps

Build docs developers (and LLMs) love

System Requirements

Backend Requirements

Frontend Requirements

Infrastructure

Installation Methods

Docker Installation

Docker Resource Limits

Manual Installation

Development Environment

Makefile Commands

Verification

Troubleshooting

Common Issues

Next Steps