Admin Development Setup

The admin dashboard is built using Go (Fiber) for the backend and React for the frontend. The admin server is integrated into the main portrd binary.

Requirements

• Go (1.25+) - Go programming language
• Bun (1.1+)
• PostgreSQL (16+) or SQLite (3.0+)

Frontend Setup

Navigate to the admin frontend directory

cd internal/server/admin/web-v2

Install frontend dependencies

bun install --frozen-lockfile

Start the frontend development server

bun run dev

This starts the React development server with hot reloading enabled.

Backend Setup

Configure environment variables

Create a new .env file in the repo root. The admin server uses the following environment variables:

PORTR_DOMAIN=localhost:8000
PORTR_DB_URL=postgres://postgres:postgres@localhost:5432/postgres
PORTR_SERVER_URL=http://localhost:8000
PORTR_SSH_URL=localhost:2222
PORTR_TUNNEL_USE_LOCALHOST=true
PORTR_ADMIN_PORT=8000
PORTR_ADMIN_DEBUG=true
PORTR_ADMIN_USE_VITE=true
PORTR_ADMIN_GITHUB_CLIENT_ID=your_github_client_id  # optional
PORTR_ADMIN_GITHUB_CLIENT_SECRET=your_github_secret  # optional
PORTR_RESERVED_SUBDOMAIN_LIMIT=3
PORTR_SSH_PORT=2222
PORTR_PROXY_PORT=8001
PORTR_AUTO_MIGRATE=true

Start the admin server

go run ./cmd/portrd start admin

This starts the admin server at http://localhost:8000. The server will automatically run database migrations if PORTR_AUTO_MIGRATE=true is set.

Alternative: Start both tunnel and admin servers

To start both the tunnel server and admin server together:

go run ./cmd/portrd start all

Development Workflow

File Structure

internal/server/admin/
├── api/               # API routes and handlers
├── db/                # Database connection helpers
├── middleware/        # HTTP middleware
├── models/            # Database models
├── scheduler/         # Background job scheduler
├── static/            # Embedded static assets
├── templates/         # HTML templates
├── utils/             # Utility functions
└── web-v2/            # React admin frontend source

Available Commands

Frontend Commands

cd internal/server/admin/web-v2
bun install --frozen-lockfile
bun run dev
bun run build

Portrd Server Commands

# Start admin server only
go run ./cmd/portrd start admin

# Start tunnel server only
go run ./cmd/portrd start tunnel

# Start both admin and tunnel servers
go run ./cmd/portrd start all

# Run database migrations manually
go run ./cmd/portrd migrate --dialect postgres

Go Development Commands

# Run tests
make testgo

# Format Go code
go fmt ./...

# Run Go linter
go vet ./...

# Tidy dependencies
go mod tidy

Configuration

For detailed configuration options, check out the server config file.

Database Management

Database Support

The admin server supports both PostgreSQL and SQLite databases:

• PostgreSQL: Recommended for production deployments
• SQLite: Great for development and single-user setups

Running Migrations

Migrations are automatically run when you start the server if PORTR_AUTO_MIGRATE=true is set. To run them manually:

# For PostgreSQL
go run ./cmd/portrd migrate --dialect postgres

# For SQLite
go run ./cmd/portrd migrate --dialect sqlite

Migration Files

Migration files are located in the migrations/ directory and are managed using goose.

Database Connection

Configure your database connection using the PORTR_DB_URL environment variable:

# PostgreSQL
PORTR_DB_URL=postgres://user:password@localhost:5432/portr

# SQLite
PORTR_DB_URL=sqlite:///path/to/database.db

For SQLite deployments, the server image can replicate the database to S3-compatible storage with Litestream. See SQLite Backups.

Troubleshooting

Common Issues

Port conflicts: Make sure ports 8000 (admin), 8001 (proxy), and 2222 (SSH) aren't being used by another service.

Database connection errors: Verify your database instance is running and the connection string is correct. For PostgreSQL, ensure the database exists and credentials are valid.

Go build errors: Ensure Go 1.25+ is installed and go mod tidy has been run to download dependencies.

Frontend build errors: Ensure Bun is installed and the lockfile is up to date. Try reinstalling dependencies with bun install --frozen-lockfile.

Migration errors: Ensure the database user has permissions to create/alter tables. For PostgreSQL, the user should have superuser privileges during initial setup.

Environment variable issues: Make sure the .env file is in the repo root and all required variables are set.

Development Tips

Hot reloading: Use PORTR_ADMIN_USE_VITE=true for frontend hot reloading during development.

Debug mode: Set PORTR_ADMIN_DEBUG=true to enable detailed logging.

Database debugging: Check the database logs for connection issues. For SQLite, ensure the database file path is writable.

API debugging: The admin server provides a health check endpoint at /api/v1/healthcheck.