Local Development Setup

Quick setup guide for running Rise locally with Docker Compose, Minikube, and the managed BuildKit daemon.

Prerequisites

• Docker or Podman
• Minikube
• Docker Compose
• Root access for /etc/hosts

Quick Setup

1. Clone and Configure Hosts

git clone https://github.com/NiklasRosenstein/rise.git
cd rise

# Add to /etc/hosts
sudo tee -a /etc/hosts <<EOF
127.0.0.1 rise.local
127.0.0.1 rise-registry
EOF

2. Configure Docker Daemon

Add to /etc/docker/daemon.json (Linux) or Docker Desktop settings:

{
  "insecure-registries": [
    "rise-registry:5000",
    "localhost:5000",
    "127.0.0.1:5000"
  ]
}

Restart Docker after changes.

3. Start Services

docker-compose up -d

4. Configure BuildKit Network

# Configure environment
export RISE_MANAGED_BUILDKIT_NETWORK_NAME=rise_default
export RISE_MANAGED_BUILDKIT_INSECURE_REGISTRIES="rise-registry:5000,localhost:5000,127.0.0.1:5000"

# Add to shell profile
cat >> ~/.bashrc <<EOF
export RISE_MANAGED_BUILDKIT_NETWORK_NAME=rise_default
export RISE_MANAGED_BUILDKIT_INSECURE_REGISTRIES="rise-registry:5000,localhost:5000,127.0.0.1:5000"
EOF

5. Start Minikube

mise run minikube:launch

This will start Minikube with registry access configured and port-forward the ingress controller.

6. Run Backend

cargo build --features backend
mise sqlx:migrate
cargo run --features backend

In a new terminal:

# Test CLI
cargo run -- login http://rise.local:8080

# Create and deploy a project
cargo run -- project create my-app
cargo run -- deploy create --image nginx:latest

Environment Variables

Troubleshooting

Registry Connection Errors

Error: http: server gave HTTP response to HTTPS client

Fix: Ensure RISE_MANAGED_BUILDKIT_INSECURE_REGISTRIES is set and contains your registry.

BuildKit Can’t Reach Registry

Error: BuildKit can’t push to rise-registry:5000

Fix: Verify RISE_MANAGED_BUILDKIT_NETWORK_NAME is set correctly:

docker inspect rise-buildkit --format '{{range $net := .NetworkSettings.Networks}}{{$net}} {{end}}'
# Should show: bridge rise_default

OAuth Redirect Issues

Error: OAuth redirects fail or redirect to wrong URL

Fix: Ensure rise.local is in /etc/hosts and Dex is configured with correct redirect URLs.

Minikube Can’t Pull Images

Error: Minikube pods fail with ImagePullBackOff

Fix: Verify registry access from within Minikube:

minikube ssh
curl http://rise-registry:5000/v2/
# Should return: {}

If it fails, ensure you used mise run minikube:launch which configures registry access automatically.

Architecture

┌─────────────────────────────────────────┐
│ Host Machine                             │
│  Rise CLI → Backend (rise.local:8080)   │
│  BuildKit → Registry (rise-registry)    │
│  Minikube ← Registry                    │
└─────────────────────────────────────────┘

Key Points:

• Registry runs in Docker Compose network
• BuildKit connects to Compose network via RISE_MANAGED_BUILDKIT_NETWORK_NAME
• Minikube accesses registry via host aliases
• All HTTP connections require insecure registry configuration

Additional Resources

• Build system details: docs/builds.md
• Development workflow: docs/development.md
• OAuth configuration: docs/oauth.md