Skip to content

QUICKSTART.md

Latest commit

 

History

History
331 lines (229 loc) · 6.44 KB

QUICKSTART.md

File metadata and controls

331 lines (229 loc) · 6.44 KB
Raw

ZipURL Quick Start Guide

Get ZipURL up and running in minutes.

Prerequisites

ZipURL uses Nix for reproducible development environments. You'll need:

  • Nix with flakes enabled
  • (Optional) direnv for automatic environment loading

Enable Nix Flakes

Add to ~/.config/nix/nix.conf or /etc/nix/nix.conf:

experimental-features = nix-command flakes

Installation

1. Clone the Repository

git clone https://github.com/nullisLabs/zipurl.git
cd zipurl

2. Enter Development Environment

# Option A: Using direnv (recommended)
direnv allow

# Option B: Manual
nix develop

The first time you run this, Nix will download and build all dependencies. This may take several minutes.

3. Install cargo-leptos

cargo install cargo-leptos

This is required for building the full-stack Leptos application.

4. Configure the Application

cp config.toml.example config.toml

Edit config.toml with your settings:

host = "0.0.0.0"
port = 1337
base_url = "http://localhost:1337"
database_path = "zipurl.db"

5. Start Development Server

just dev
# or
cargo leptos watch

The application will be available at http://localhost:1337

Hot reload is enabled - any code changes will automatically rebuild and refresh.

First Steps

Access the Application

  1. Open http://localhost:1337 in your browser
  2. The database will be created automatically on first run

Configure Authentication (Optional)

ZipURL supports multiple auth modes:

Mock Authentication (Development)

Edit config.toml:

[auth]
mode = "mock"

OIDC/Keycloak (Production)

  1. Start Keycloak for testing:
just keycloak-up
  1. Configure in config.toml:
[auth]
mode = "keycloak"
issuer_url = "http://localhost:8080/realms/master"
client_id = "zipurl"
client_secret = "your-client-secret"
redirect_uri = "http://localhost:1337/auth/callback"
  1. Access Keycloak admin console:

Create Your First Short URL

Via Web UI

  1. Log in (if auth is enabled)
  2. Navigate to Dashboard
  3. Click "Create Short URL"
  4. Enter target URL and optional custom code
  5. Add UTM parameters or metadata if needed
  6. Click "Create"

Via API

Generate an API key first:

# Generate a random key
just gen-api-key

# Hash it for storage (you'll need to add to database manually)
just hash-api-key YOUR_KEY_HERE

Then create a URL:

curl -X POST http://localhost:1337/api/urls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "localhost",
    "target_url": "https://example.com",
    "code": "example"
  }'

Access your short URL at: http://localhost:1337/example

Common Commands

# Development
just dev              # Start dev server
just dev-server       # Backend only (no SSR)

# Testing
just test             # Run all tests
just test-one <name>  # Run specific test

# Code Quality
just fmt              # Format code
just lint             # Run linter
just check-all        # Check frontend & backend

# Database
just db-backup        # Backup database
just db-reset         # Reset database (WARNING: deletes data)

# Building
just build            # Development build
just build-release    # Production build

# Help
just --list           # Show all commands
just help             # Show help

Project Structure

zipurl/
├── crates/
│   ├── zipurl-core/      # Shared models and types
│   ├── zipurl-server/    # Backend API and database
│   ├── zipurl-client/    # Browser-side utilities
│   └── zipurl-app/       # Leptos UI application
├── assets/               # Static assets
├── config.toml.example   # Configuration template
├── Justfile              # Task runner commands
├── Leptos.toml          # Leptos build config
└── flake.nix            # Nix development environment

Troubleshooting

Build Errors

Problem: WASM compilation fails

# Check frontend compilation
just check-frontend

# Ensure wasm32 target is installed
rustup target add wasm32-unknown-unknown

Problem: Missing cargo-leptos

cargo install cargo-leptos

Runtime Errors

Problem: Port 1337 already in use

Edit config.toml or Leptos.toml to change the port.

Problem: Database locked or corrupted

just db-reset  # WARNING: This deletes all data

Authentication Issues

Problem: Keycloak connection fails

# Check Keycloak is running
just keycloak-logs

# Restart Keycloak
just keycloak-reset

Problem: OIDC redirect loop

Verify redirect_uri in config.toml matches your Keycloak client configuration.

Development Tips

Hot Reload

The dev server watches for changes in:

  • Rust files (.rs)
  • Tailwind CSS (style/tailwind.css)
  • Static assets

Changes trigger automatic rebuild and browser refresh.

Debugging

Enable Rust backtraces:

RUST_BACKTRACE=1 just dev

Enable debug logging:

RUST_LOG=debug just dev

Testing Individual Crates

# Test specific crate
cargo test -p zipurl-server
cargo test -p zipurl-core

# Test with output
cargo test -- --nocapture

Frontend-Only Development

just check-frontend-quick  # Fast compilation check
just build-frontend        # Build WASM only

Next Steps

  • Read CLAUDE.md for detailed architecture documentation
  • Check Justfile for all available commands
  • Explore the API endpoints in crates/zipurl-server/src/api/
  • Customize the UI in crates/zipurl-app/src/

Production Deployment

For production deployment:

  1. Build release version:
just build-release
  1. Binary location: target/release/zipurl-app
  2. Static assets: target/site/
  3. Set environment variables for sensitive config
  4. Use reverse proxy (nginx/caddy) with HTTPS
  5. Configure OIDC for production auth
  6. Set up regular database backups

See README.md for more deployment options.

Getting Help

  • Check existing issues on GitHub
  • Review CLAUDE.md for development guidance
  • Run just help for command reference

Additional Resources