Skip to content
<awesome-gh-repos>
vic

noelukwa/localbase

localbase is a lightweight tool for provisioning secure .local domains. It simplifies the process of setting up local development environments with HTTPS support.
Source code at GitHub https://github.com/noelukwa/localbase
noelukwa/localbase.json
{
  "createdAt": "2024-06-25T08:18:19Z",
  "defaultBranch": "main",
  "description": "localbase is a lightweight tool for provisioning secure .local domains. It simplifies the process of setting up local development environments with HTTPS support.",
  "fullName": "noelukwa/localbase",
  "homepage": "",
  "language": "Go",
  "name": "localbase",
  "pushedAt": "2025-08-16T01:20:56Z",
  "stargazersCount": 27,
  "topics": [
    "golang",
    "localhost",
    "tunnel"
  ],
  "updatedAt": "2025-11-14T00:26:22Z",
  "url": "https://github.com/noelukwa/localbase"
}

LocalBase

Section titled “LocalBase”

A secure, lightweight tool for provisioning .local domains with automatic HTTPS support. LocalBase simplifies local development by managing Caddy reverse proxy configurations and mDNS service discovery.

Features

Section titled “Features”
  • 🔒 Secure by default - Token-based authentication and TLS encryption
  • 🚀 Zero-config HTTPS - Automatic certificate generation and management
  • 🌐 mDNS integration - Automatic .local domain resolution
  • 🔄 Hot reloading - Dynamic domain addition/removal without restarts
  • 🎯 Production ready - Comprehensive logging, error handling, and monitoring
  • ⚡ Lightweight - Minimal resource usage with connection pooling

Requirements

Section titled “Requirements”
  • Caddy - Web server with automatic HTTPS
  • Go 1.21+ - For installation from source

Installation

Section titled “Installation”

🚀 Quick Install (Recommended)

Section titled “🚀 Quick Install (Recommended)”
Terminal window
curl -sSL https://raw.githubusercontent.com/noelukwa/localbase/main/install.sh | sudo sh

🍺 Homebrew (Coming Soon)

Section titled “🍺 Homebrew (Coming Soon)”
Terminal window
# Homebrew support coming soon
# For now, use quick install or binary download

💾 Binary Download

Section titled “💾 Binary Download”
Terminal window
# Download latest release for your platform
wget https://github.com/noelukwa/localbase/releases/latest/download/localbase_linux_x86_64.tar.gz
tar -xzf localbase_linux_x86_64.tar.gz
sudo mv localbase /usr/local/bin/

🛠️ Go Install

Section titled “🛠️ Go Install”
Terminal window
go install github.com/noelukwa/localbase@latest

🔧 Build from Source

Section titled “🔧 Build from Source”
Terminal window
git clone https://github.com/noelukwa/localbase.git
cd localbase
go build -o localbase .

Quick Start

Section titled “Quick Start”

  1. Start LocalBase service:

    Terminal window
    localbase start

  2. Add a domain (in another terminal):

    Terminal window
    localbase add myapp --port 3000

  3. Start your application on port 3000

  4. Visit https://myapp.local 🎉

Usage

Section titled “Usage”

Service Management

Section titled “Service Management”
Terminal window
# Start in foreground
localbase start


# Start in daemon mode
localbase start -d


# Stop service
localbase stop


# Check service status
localbase status

Domain Management

Section titled “Domain Management”
Terminal window
# Add domain pointing to local service
localbase add hello --port 3000


# Remove domain
localbase remove hello


# List all domains
localbase list


# Health check
localbase ping

Configuration

Section titled “Configuration”

LocalBase stores configuration in:

  • macOS: ~/Library/Application Support/localbase/
  • Linux: ~/.config/localbase/
  • Windows: %APPDATA%\localbase\

Default configuration:

{
  "caddy_admin": "http://localhost:2019",
  "admin_address": "localhost:2025"
}

Development

Section titled “Development”

Running Tests

Section titled “Running Tests”
Terminal window
go test ./... -v

Running Benchmarks

Section titled “Running Benchmarks”
Terminal window
go test -bench=. -benchmem

Code Coverage

Section titled “Code Coverage”
Terminal window
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Contributing

Section titled “Contributing”
  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Run tests (go test ./...)
  4. Commit changes (git commit -m 'Add amazing feature')
  5. Push to branch (git push origin feature/amazing-feature)
  6. Open a Pull Request

License

Section titled “License”

This project is licensed under the MIT License - see the [LICENSE]!(LICENSE) file for details.

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”

“Caddy not found”

Terminal window
# Install Caddy
brew install caddy  # macOS
sudo apt install caddy  # Ubuntu/Debian

“Permission denied”

Terminal window
# Check file permissions
ls -la ~/.config/localbase/

“Connection refused”

Terminal window
# Check if service is running
localbase status

Debug Mode

Section titled “Debug Mode”

Enable debug logging:

Terminal window
LOCALBASE_LOG_LEVEL=debug localbase start