Getting Started

This guide will help you get Locky up and running on your local machine.

Prerequisites

Go 1.22+: Download
MySQL 8.0+ or TiDB: Database server
Redis 6.0+: Cache server
Docker & Docker Compose (optional): For quick setup

Quick Start with Docker Compose

The fastest way to get started:

# Clone the repository
git clone https://github.com/ryo-arima/locky.git
cd locky

# Start MySQL and Redis
docker-compose up -d

# Copy development configuration
cp etc/app.dev.yaml etc/app.yaml

# Run database migrations (if any)
# TODO: Add migration commands

# Build the server
go build -o .bin/locky-server ./cmd/server/main.go

# Start the server
./.bin/locky-server

The server will start on http://localhost:8080.

Manual Setup

1. Install Dependencies

# Install Go dependencies
go mod download
go mod vendor

2. Setup Database

# Create MySQL database
mysql -u root -p
> CREATE DATABASE locky;
> CREATE USER 'locky'@'localhost' IDENTIFIED BY 'password';
> GRANT ALL PRIVILEGES ON locky.* TO 'locky'@'localhost';
> FLUSH PRIVILEGES;

3. Setup Redis

# Start Redis (macOS with Homebrew)
brew services start redis

# Or with Docker
docker run -d -p 6379:6379 redis:alpine

4. Configure Application

# Copy configuration template
cp etc/app.yaml.example etc/app.yaml

# Edit configuration
vi etc/app.yaml

Update the following sections:

MySQL connection details
Redis connection details
JWT secrets

5. Build the Application

# Build all binaries
make build

# Or build individually
go build -o .bin/locky-server ./cmd/server/main.go
go build -o .bin/locky-client-admin ./cmd/client/admin/main.go
go build -o .bin/locky-client-app ./cmd/client/app/main.go
go build -o .bin/locky-client-anonymous ./cmd/client/anonymous/main.go

6. Run the Server

./.bin/locky-server

Verify Installation

Check Server Status

# Health check
curl http://localhost:8080/v1/public/health

# Expected response:
# {"status": "ok"}

Register a User

curl -X POST http://localhost:8080/v1/public/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test User",
    "email": "test@example.com",
    "password": "securepassword"
  }'

curl -X POST http://localhost:8080/v1/public/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "securepassword"
  }'

# Save the JWT token from response
export TOKEN="<jwt_token_here>"

Access Protected Endpoint

curl http://localhost:8080/v1/internal/users \
  -H "Authorization: Bearer $TOKEN"

Using the CLI Clients

Admin Client

./.bin/locky-client-admin --help

App Client

./.bin/locky-client-app --help

Anonymous Client

./.bin/locky-client-anonymous --help

Makefile Commands

Locky includes a Makefile for common tasks:

# Build all binaries
make build

# Run tests
make test

# Clean build artifacts
make clean

# Generate documentation
make docs

# Start development environment
make dev-up

# Stop development environment
make dev-down

Development Workflow

Make Changes: Edit source code
Build: make build
Test: make test
Run: ./.bin/locky-server
Verify: Test with curl or CLI clients

Troubleshooting

Port Already in Use

# Find process using port 8080
lsof -i :8080

# Kill the process
kill -9 <PID>

Database Connection Failed

Verify MySQL is running: mysql -u root -p
Check credentials in etc/app.yaml
Ensure database exists: SHOW DATABASES;

Redis Connection Failed

Verify Redis is running: redis-cli ping
Check Redis host/port in configuration
Test connection: redis-cli -h localhost -p 6379

Casbin Policy Errors

Verify policy files exist in etc/casbin/
Check CSV format (no trailing commas)
Validate model syntax

Locky Documentation