LilURL is a high-performance URL shortener service built with Go and the Fiber web framework. It provides a simple and efficient way to create shortened URLs with a clean RESTful API.
- Fast & Lightweight: Built with Fiber v3 (beta) for exceptional performance
- RESTful API: Clean and intuitive API design
- SQLite Database: Lightweight, file-based database perfect for URL storage
- Docker Support: Easy deployment with Docker and docker-compose
- URL Validation: Built-in validation for URLs
- Soft Deletion: URLs are soft-deleted, maintaining data integrity
- Configurable: YAML-based configuration with environment variable support
- Structured Logging: Production-ready logging with slog
- Two Shortening Algorithms: Base62 encoding and SHA256-based generation
- Prerequisites
- Installation
- Configuration
- API Documentation
- Development
- Testing
- Deployment
- Project Structure
- Contributing
- License
- Go 1.23.0 or higher
- Docker and Docker Compose (for containerized deployment)
- Make (for using Makefile commands)
- dbmate (for database migrations)
- CGO enabled (required for SQLite)
git clone https://github.com/pansachin/lilurl.git
cd lilurlgo mod download# Create .env file for database configuration
echo "DATABASE_URL=sqlite:schema/lilurl.db" > .env
# Run migrations
make migrate# Build the binary (CGO required for SQLite)
CGO_ENABLED=1 go build -o lilurl .
# Run the application
./lilurlThe application will start on http://localhost:3000 by default.
LilURL uses a layered configuration approach:
- Default Configuration (
config.yaml) - Production Configuration (
/config/config.yamlin container) - Environment Variables (override any setting)
app:
name: "lilurl"
host: "localhost"
port: 3000
db:
instance: "sqlite3"
port: "3001"
user: "user"
password: "password"
database: "lilurl"
log:
debug: true
json: true
colour: true
print_routes: falseDATABASE_URL: SQLite database connection string (e.g.,sqlite:schema/lilurl.db)APP_PORT: Override the default port (default: 3000)LOG_DEBUG: Enable debug logging (true/false)
POST /api/v1/lilurl
curl -X POST http://localhost:3000/api/v1/lilurl \
-H "Content-Type: application/json" \
-d '{"long_url": "https://github.com/pansachin/lilurl"}'Request Body:
{
"long_url": "https://github.com/pansachin/lilurl"
}Response:
{
"id": 1,
"long_url": "https://github.com/pansachin/lilurl",
"short": "abc123d",
"created_at": "2024-10-26T10:30:00Z"
}GET /:lilurl
curl -L http://localhost:3000/abc123dRedirects to the original URL with a 301 status code.
GET /api/v1/:lilurl
curl http://localhost:3000/api/v1/abc123dResponse:
{
"id": 1,
"long_url": "https://github.com/pansachin/lilurl",
"short": "abc123d",
"created_at": "2024-10-26T10:30:00Z",
"updated_at": "2024-10-26T10:30:00Z"
}GET /api/v1/:id
curl http://localhost:3000/api/v1/1# Run tests
make test
# Build Docker image
make build
# Run in Docker environment (builds and runs)
make run
# Clean up Docker containers
make clean
# Remove specific container
make rm# Run tests with verbose output
go test -v ./...
# Run with hot reload (using air)
air
# Build for production
CGO_ENABLED=1 go build -ldflags "-s -w" -o lilurl .Migrations are managed using dbmate and stored in schema/migrations/:
# Create a new migration
dbmate new create_users_table
# Apply migrations
make migrate
# Rollback migrations
dbmate rollback# Run all tests
go test ./...
# Run tests with coverage
go test -cover ./...
# Run tests with race detector
go test -race ./...
# Run specific test
go test -v ./config -run TestConfig# Build and run with docker-compose
docker-compose up --build
# Run in detached mode
docker-compose up -d
# View logs
docker-compose logs -f lilurl# Build for Google Artifact Registry
make build-ar GAR=<registry-url>
# Push to registry
make push-ar GAR=<registry-url>The project includes an Nginx reverse proxy configuration in proxy/nginx.conf for production deployments.
lilurl/
├── app/ # Application layer
│ ├── handlers/ # HTTP handlers
│ │ ├── routes.go # Route definitions
│ │ └── lilurl/ # LilURL handler implementation
│ └── models/ # Data models and DB logic
├── config/ # Configuration management
│ ├── config.go # Config struct and loader
│ └── config_test.go # Config tests
├── internal/ # Private packages
│ └── pkg/
│ └── generator/ # URL shortening algorithms
├── pkg/ # Public packages
│ ├── database/ # Database utilities
│ │ └── sqlite/ # SQLite initialization
│ └── log/ # Logging setup
├── schema/ # Database schema
│ ├── migrations/ # Database migrations
│ └── lilurl.db # SQLite database file
├── proxy/ # Proxy configuration
│ └── nginx.conf # Nginx configuration
├── main.go # Application entry point
├── Dockerfile # Docker configuration
├── docker-compose.yaml # Docker Compose setup
├── Makefile # Build automation
├── go.mod # Go module definition
├── go.sum # Go module checksums
├── config.yaml # Default configuration
└── README.md # This file
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
- Follow Go best practices and idioms
- Ensure all tests pass before submitting PR
- Add tests for new features
- Update documentation as needed
- Use conventional commit messages
This project is licensed under the MIT License - see the LICENSE file for details.
- Fiber - The web framework used
- SQLite - The database engine
- sqlx - Database toolkit
- cleanenv - Configuration management
Made with ❤️ by @pansachin