roji

CLI Reference

Mon, 01 Jan 2024 00:00:00 +0000

`roji`

Start the reverse proxy server.

sudo roji # Run in foreground
sudo roji --network web,api # Watch multiple networks
sudo roji --domain test.localhost # Custom domain
sudo roji --http-port 8080 --https-port 8443 # Custom ports
sudo roji --log-level debug # Verbose logging

Flags:

Common Issues

Mon, 01 Jan 2024 00:00:00 +0000

First Step: Run `roji doctor`

Always start with diagnostics:

roji doctor # Check for issues
sudo roji doctor --fix # Auto-fix where possible

This checks Docker, networking, certificates, ports, and DNS — and can fix most common problems automatically.

Configuration

Mon, 01 Jan 2024 00:00:00 +0000

roji can be configured through a config file, environment variables, or CLI flags.

Config File

Location: ~/.config/roji/config.yaml

network: roji  # Docker network(s) to watch (comma-separated)
domain: dev.localhost  # Base domain
http_port: 80 # HTTP port (redirect to HTTPS)
https_port: 443 # HTTPS port
certs_dir: ~/.local/share/roji/certs  # Certificate directory
data_dir: ~/.local/share/roji  # Data directory
dashboard: roji.dev.localhost  # Dashboard hostname
log_level: info  # Log level (debug, info, warn, error)
auto_cert: true # Auto-generate certificates

static_sites: # Static file hosting (see Static Sites guide)
 - host: docs
 root: ~/projects/docs/build

Managing the Config File

roji config show # Display current settings
roji config path # Show config file locations
roji config init # Create default config file
roji config edit # Open in $EDITOR

Environment Variables

Variable	Description	Default
`ROJI_NETWORK`	Docker network(s) to watch (comma-separated)	`roji`
`ROJI_DOMAIN`	Base domain	`dev.localhost`
`ROJI_HTTP_PORT`	HTTP port	`80`
`ROJI_HTTPS_PORT`	HTTPS port	`443`
`ROJI_CERTS_DIR`	Certificate directory	`~/.local/share/roji/certs`
`ROJI_DATA_DIR`	Data directory (project history)	`~/.local/share/roji`
`ROJI_DASHBOARD`	Dashboard hostname	`roji.{domain}`
`ROJI_LOG_LEVEL`	Log level	`info`
`ROJI_AUTO_CERT`	Auto-generate certificates	`true`

Settings Priority

Settings are applied in this order (highest priority first):

Installation

Mon, 01 Jan 2024 00:00:00 +0000

Homebrew (macOS)

brew install kan/roji/roji

One-liner Install (Recommended)

Works on Linux and macOS:

curl -fsSL https://raw.githubusercontent.com/kan/roji/v1.0.0/install.sh | bash

This will:

Docker Labels

Mon, 01 Jan 2024 00:00:00 +0000

Label Reference

Label	Description	Default
`roji.host`	Custom hostname	`{service}.dev.localhost`
`roji.port`	Target port	First EXPOSE’d port
`roji.path`	Path prefix	none
`roji.mock.{METHOD}.{PATH}`	Mock response body	none
`roji.mock.status.{METHOD}.{PATH}`	Mock response status code	`200`
`roji.auth.basic.user`	Basic auth username	none
`roji.auth.basic.pass`	Basic auth password	none
`roji.auth.basic.realm`	Basic auth realm	`Restricted`
`roji.self`	Reserved: excludes container from routing (internal use)	none

`roji.host`

Override the default hostname ({service}.dev.localhost):

Quick Start

Mon, 01 Jan 2024 00:00:00 +0000

Prerequisites

Docker with Docker Compose v2
roji installed and running (see Installation)

Verify Setup

roji doctor

All checks should pass. If not, run sudo roji doctor --fix to auto-repair.

Static File Hosting

Mon, 01 Jan 2024 00:00:00 +0000

roji can serve static files directly without Docker containers, using the static_sites section in the config file.

Configuration

Add entries to ~/.config/roji/config.yaml:

WSL

Mon, 01 Jan 2024 00:00:00 +0000

Certificates

You need to install the CA certificate in both Linux and Windows for browsers to trust HTTPS:

sudo roji ca install # Linux trust store
sudo roji ca install --windows # Windows trust store (for Chrome/Edge on Windows)

The --windows flag uses certutil.exe to install the certificate in the Windows user certificate store (CurrentUser\ROOT).

Basic Authentication

Mon, 01 Jan 2024 00:00:00 +0000

roji supports HTTP Basic Authentication to protect routes in your local development environment.

Via Docker Labels

Add authentication to any Docker-based route:

Environment Variables

Mon, 01 Jan 2024 00:00:00 +0000

Variable Reference

Variable	Description	Default
`ROJI_NETWORK`	Docker network(s) to watch (comma-separated)	`roji`
`ROJI_DOMAIN`	Base domain for service hostnames	`dev.localhost`
`ROJI_HTTP_PORT`	HTTP port (redirects to HTTPS)	`80`
`ROJI_HTTPS_PORT`	HTTPS port	`443`
`ROJI_CERTS_DIR`	Directory for TLS certificates	`~/.local/share/roji/certs`
`ROJI_DATA_DIR`	Directory for data (project history, logs)	`~/.local/share/roji`
`ROJI_DASHBOARD`	Dashboard hostname	`roji.{domain}`
`ROJI_LOG_LEVEL`	Log level (`debug`, `info`, `warn`, `error`)	`info`
`ROJI_AUTO_CERT`	Auto-generate TLS certificates	`true`

Usage

# Run with custom settings
ROJI_DOMAIN=test.localhost ROJI_LOG_LEVEL=debug sudo roji

# Watch multiple networks
ROJI_NETWORK=web,api sudo roji

# Use alternative ports
ROJI_HTTP_PORT=8080 ROJI_HTTPS_PORT=8443 sudo roji

Priority

Environment variables override config file values but are overridden by CLI flags:

roji

CLI Reference

roji

Common Issues

First Step: Run roji doctor

Configuration

Config File

Managing the Config File

Environment Variables

Settings Priority

Installation

Homebrew (macOS)

One-liner Install (Recommended)

Docker Labels

Label Reference

roji.host

Quick Start

Prerequisites

Verify Setup

Static File Hosting

Configuration

WSL

Certificates

Basic Authentication

Via Docker Labels

Environment Variables

Variable Reference

Usage

Priority

`roji`

First Step: Run `roji doctor`

`roji.host`