Skip to main content

Dev Deployment

The dev deployment provides a complete infrastructure stack without the Safebucket application container, designed for contributors and developers actively working on the Safebucket codebase.

Overview​

What's Included​

This deployment includes all the infrastructure services Safebucket needs:

  • PostgreSQL 18 - Main database
  • RustFS - High-performance S3-compatible object storage
  • Valkey 9 - Caching layer
  • NATS JetStream - Event streaming
  • Loki - Activity logging
  • Mailpit - Email testing
  • Grafana (optional) - Logs visualization for debugging

Prerequisites​

Quick Start​

  1. Clone the repository:

    git clone https://github.com/safebucket/safebucket
    cd safebucket/deployments/dev

  2. Start the infrastructure:

    docker compose up -d

  3. Verify services are running:

    docker compose ps

  4. Run Safebucket locally:

    # Build the frontend
    cd web
    npm install
    npm run dev

    # Run the backend
    cd ..
    go run main.go

  5. Access Safebucket: Open http://localhost:3000 in your browser

Services Overview​

ServicePortPurpose
PostgreSQL5432Main database
RustFS API9000Object storage API
RustFS Console9001RustFS web console
Valkey6379Caching layer
NATS4222Event streaming
Loki3100Activity logging
Mailpit Web8025Email testing UI
Mailpit SMTP1025Email testing SMTP
Grafana*3200Logs visualization

* Grafana only starts with --profile debug

Running Safebucket Locally​

Step-by-Step Guide​

1. Start Infrastructure​

cd deployments/dev
docker compose up -d

Wait for all services to be healthy:

docker compose ps

You should see (healthy) status for database and bucket services.

3. Build Frontend (First Time)​

cd web
npm install
npm run build
cd ..

This creates a production build in web/dist that the backend will serve.

4. Run Backend​

From the project root:

go run main.go

The application will:

  1. Connect to the database
  2. Run migrations
  3. Initialize services
  4. Start the HTTP server on port 8080

5. Access the Application​

Open http://localhost:3000 and log in with:

Connection Endpoints​

When running Safebucket locally, use these connection strings:

ServiceEndpointCredentials
PostgreSQLlocalhost:5432User: safebucket-user
Pass: safebucket-password
DB: safebucket
RustFS APIlocalhost:9000Access Key: rustfsadmin
Secret: rustfsadmin
Valkeylocalhost:6379Password: safebucket-password
NATSlocalhost:4222No auth
Lokihttp://localhost:3100No auth
Mailpit Webhttp://localhost:8025No auth
Mailpit SMTPlocalhost:1025No auth

Running Tests​

# Run all tests
go test ./...

# Run specific package tests
go test ./internal/services

# Run with coverage
go test -cover ./...

Testing Email​

Mailpit captures all emails sent by Safebucket:

  1. Open http://localhost:8025
  2. Perform actions that send emails (user invites, password resets)
  3. View emails in Mailpit UI

Accessing Storage​

RustFS provides S3-compatible storage without a web console. To manage buckets and files, you can use:

  • AWS CLI: Configure with RustFS credentials

    aws configure --profile rustfs
    # Access Key: rustfsadmin
    # Secret Key: rustfsadmin
    # Region: us-east-1
    # Output: json

    aws --profile rustfs --endpoint-url http://localhost:9000 s3 ls s3://safebucket

  • S3 Browser Tools: Any S3-compatible client (e.g., Cyberduck, S3 Browser)

Architecture Differences: Dev vs Local​

FeatureDev DeploymentLocal Deployment
Safebucket AppRun locally from sourceDockerized container
PurposeActive developmentTesting, demos
Iteration SpeedFast (no rebuild)Slower (rebuild image)
DebuggingFull IDE supportLog-based
Hot ReloadYes (with Air/CompileDaemon)No
Resource UsageLower (no app container)Higher
Container ImagesOfficial imagesSame
Health ChecksSame infrastructure reliabilitySame
Best ForDevelopment, contributingIntegration testing, demos

Configuration Files​

The dev deployment uses:

  • deployments/dev/docker-compose.yml: Service definitions
  • deployments/dev/.env: Infrastructure environment variables
  • config.yaml or app-level .env: Your local Safebucket configuration

Note: Infrastructure .env configures Docker services. App configuration should be set separately when running locally.

Next Steps​