Skip to content

local-development.md

Latest commit

 

History

History
127 lines (89 loc) · 3.02 KB

local-development.md

File metadata and controls

127 lines (89 loc) · 3.02 KB

💻 Run Locally (Development)

Use this path if you want to modify the source code and run from your workstation.

⚠️ Security Warning: This guide is for development and testing only. For production deployments, see Security Hardening Guide and Production Rollout Guide.

Current Security Defaults

  • AUTH_TOKEN_EXPIRATION_SECONDS default is 14400 (4 hours)
  • RATE_LIMIT_ENABLED default is true (per authenticated client)
  • RATE_LIMIT_TOKEN_ENABLED default is true (per IP on POST /v1/token)
  • CORS_ENABLED default is false

These defaults were introduced in v0.5.0 with token-endpoint rate limiting added in v0.7.0 .

Prerequisites

  • Go 1.25+
  • Docker (for local database)

1) Clone and install dependencies

git clone https://github.com/allisson/secrets.git
cd secrets
go mod download

2) Build

make build

3) Generate master key and set .env

KMS mode is required as of v0.19.0. For local development, use the localsecrets provider:

# Generate a KMS encryption key (32 random bytes, base64-encoded)
KMS_KEY=$(openssl rand -base64 32)

# Create master key with KMS encryption
./bin/app create-master-key --id default \
  --kms-provider=localsecrets \
  --kms-key-uri="base64key://${KMS_KEY}"

# Copy example environment file
cp .env.example .env

The command output will include:

  • KMS_PROVIDER and KMS_KEY_URI (already set if you used the command above)
  • MASTER_KEYS - paste this into your .env file
  • ACTIVE_MASTER_KEY_ID - paste this into your .env file

Your .env file should look like:

KMS_PROVIDER=localsecrets
KMS_KEY_URI=base64key://<generated-key>
MASTER_KEYS=default:<kms-encrypted-value>
ACTIVE_MASTER_KEY_ID=default

4) Start PostgreSQL

make dev-postgres

Default connection in .env can be:

DB_DRIVER=postgres
DB_CONNECTION_STRING=postgres://user:password@localhost:5432/mydb?sslmode=disable

5) Migrate and create KEK

./bin/app migrate
./bin/app create-kek --algorithm aes-gcm

6) Start server

./bin/app server

7) Create first client credentials

In another terminal, create your first API client and policy set:

./bin/app create-client \
  --name bootstrap-admin \
  --active \
  --policies '[{"path":"*","capabilities":["read","write","delete","encrypt","decrypt","rotate"]}]' \
  --format json

Save the returned client_id and one-time secret securely.

8) Issue token

curl -X POST http://localhost:8080/v1/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"<client-id>","client_secret":"<client-secret>"}'

9) Smoke test

curl http://localhost:8080/health

See also