Dyno

A self-hostable, open-source DuckDNS alternative

Lightweight dynamic DNS service that lets you manage your DNS records without manual overhead.

Features • Quick Start • Documentation • API Reference • Contributing

📖 Overview

Dyno is a self-hosted dynamic DNS service that eliminates the manual overhead of managing DNS records. Bring your own domain and Cloudflare tokens, and let Dyno handle the rest. Perfect for home labs, development environments, and self-hosted infrastructure.

Why Dyno?

🏠 Self-Hosted: Complete control over your DNS data
🔐 Secure: Token-based authentication for all operations
🚀 Fast: Built with Go for optimal performance
🔌 API-First: Comprehensive RESTful API for CLI/script automation
📦 Easy Setup: Docker support with minimal configuration
🌐 Cloudflare Integration: Currently supports Cloudflare DNS (more providers coming soon)
💾 Persistent Storage: PostgreSQL database for reliability

📖 Detailed Documentation: Visit docs.dyno.rndmcode.in for comprehensive guides, tutorials, and API documentation.

✨ Features

Dynamic DNS Updates: Automatically update your DNS records when your IP changes
Multi-User Support: User authentication and authorization system
RESTful API: Full-featured API for programmatic access
Domain Management: Create, read, update, and delete DNS records
IPv4 Support: Automatic IP detection and DNS record updates
CLI-Friendly: Simple GET endpoints for easy curl-based updates
Dashboard Ready: API designed for web dashboard integration
Docker Support: Easy deployment with Docker and Docker Compose
CI/CD Pipeline: Automated builds and deployments with GitHub Actions

🚀 Quick Start

Prerequisites

Go 1.24+ (for local development)
PostgreSQL 12+
Docker & Docker Compose (recommended)
Cloudflare Account with API token
Your own domain managed by Cloudflare

Installation

Option 1: Docker (Recommended)

Pull the Docker image:

docker pull ghcr.io/rndmcodeguy20/dyno:production

Create a .env file:

# Server Configuration
ENV=production
HOST=0.0.0.0
PORT=5010

# Database Configuration
DB_HOST=postgres
DB_PORT=5432
DB_USER=dyno
DB_PASSWORD=your_secure_password
DB_NAME=dyno_db

# Cloudflare Configuration
PROVIDER_API_KEY=your_cloudflare_api_token
PROVIDER_EMAIL=your_cloudflare_email
DOMAIN=yourdomain.com

Create a docker-compose.yml:

version: '3.8'

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: dyno_db
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./db/migrations:/docker-entrypoint-initdb.d
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5

  dyno:
    image: ghcr.io/rndmcodeguy20/dyno:latest
    env_file:
      - .env
    ports:
      - "5010:5010"
    depends_on:
      postgres:
        condition: service_healthy
    restart: unless-stopped

volumes:
  postgres_data:

Start the services:
```
docker-compose up -d
```

Option 2: Build from Source

Clone the repository:

git clone https://github.com/rndmcodeguy20/dyno.git
cd dyno

Install dependencies:
```
go mod download
```

Set up PostgreSQL:

# Run the migration scripts in db/migrations/
psql -U postgres -f db/migrations/001_seed.sql
psql -U postgres -d dyno_db -f db/migrations/002_unique_constraints_domain.sql
psql -U postgres -d dyno_db -f db/migrations/003_add_dns_record_ids.sql
psql -U postgres -d dyno_db -f db/migrations/004_add_token_hash_users.sql

Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

Build and run:

go build -o dyno ./cmd/server/main.go
./dyno

🔧 Configuration

Environment Variables

Variable	Description	Required	Default
`ENV`	Environment (development/staging/production)	Yes	-
`HOST`	Server host address	No	`0.0.0.0`
`PORT`	Server port	No	`5010`
`DB_HOST`	PostgreSQL host	Yes	-
`DB_PORT`	PostgreSQL port	No	`5432`
`DB_USER`	Database username	Yes	-
`DB_PASSWORD`	Database password	Yes	-
`DB_NAME`	Database name	Yes	-
`PROVIDER_API_KEY`	Cloudflare API token	Yes	-
`PROVIDER_EMAIL`	Cloudflare account email	Yes	-
`DOMAIN`	Your domain name	Yes	-

Getting a Cloudflare API Token

Log in to your Cloudflare Dashboard
Go to My Profile → API Tokens
Click Create Token
Use the Edit zone DNS template
Configure permissions:
- Zone → DNS → Edit
- Zone Resources → Include → Specific zone → your domain
Copy the generated token to PROVIDER_API_KEY

📚 API Reference

Base URL

http://localhost:5010/api/v1

Authentication

All protected endpoints require a token in the Authorization header:

Authorization: Bearer <your_token>

Endpoints

Authentication

Sign Up

POST /api/v1/auth/signup
Content-Type: application/json

{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "securepassword"
}

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "username": "johndoe",
  "password": "securepassword"
}

Response:

{
  "success": true,
  "data": {
    "token": "your_auth_token",
    "user": {
      "id": 1,
      "username": "johndoe",
      "email": "john@example.com"
    }
  }
}

Domain Management

List Domains

GET /api/v1/domains
Authorization: Bearer <token>

Create Domain

POST /api/v1/domain
Authorization: Bearer <token>
Content-Type: application/json

{
  "domain_name": "home.yourdomain.com",
  "current_ip_v4": "203.0.113.10"
}

Update Domain by Name (CLI-Friendly)

# Automatic IP detection
curl "http://localhost:5010/api/v1/domain/update?domain=home.yourdomain.com&token=your_token"

# Explicit IP
curl "http://localhost:5010/api/v1/domain/update?domain=home.yourdomain.com&ip=203.0.113.10&token=your_token"

Update Domain by ID (RESTful)

PUT /api/v1/domain/{domainId}
Authorization: Bearer <token>
Content-Type: application/json

{
  "current_ip_v4": "203.0.113.20"
}

Delete Domain

DELETE /api/v1/domain/{domainId}
Authorization: Bearer <token>

User Profile

Get User Profile

GET /api/v1/user/profile
Authorization: Bearer <token>

🛠️ Usage Examples

Automated IP Updates with Cron

Create a script to update your IP automatically:

#!/bin/bash
# update-ip.sh

TOKEN="your_auth_token"
DOMAIN="home.yourdomain.com"
DYNO_URL="http://localhost:5010"

curl -s "${DYNO_URL}/api/v1/domain/update?domain=${DOMAIN}&token=${TOKEN}"

Add to crontab to run every 5 minutes:

*/5 * * * * /path/to/update-ip.sh

Python Script

import requests

DYNO_URL = "http://localhost:5010/api/v1"
TOKEN = "your_auth_token"

headers = {"Authorization": f"Bearer {TOKEN}"}

# List domains
response = requests.get(f"{DYNO_URL}/domains", headers=headers)
print(response.json())

# Update domain
response = requests.get(
    f"{DYNO_URL}/domain/update",
    params={"domain": "home.yourdomain.com"},
    headers=headers
)
print(response.json())

PowerShell Script (Windows)

$token = "your_auth_token"
$domain = "home.yourdomain.com"
$dynoUrl = "http://localhost:5010"

$headers = @{
    "Authorization" = "Bearer $token"
}

Invoke-RestMethod -Uri "$dynoUrl/api/v1/domain/update?domain=$domain" -Headers $headers

🏗️ Architecture

Tech Stack

Language: Go 1.24
Web Framework: Chi Router
Database: PostgreSQL with sqlx
DNS Provider SDK: Cloudflare Go SDK v6
Logging: Uber Zap
Authentication: Token-based (bcrypt hashing)

Project Structure

dyno/
├── cmd/
│   └── server/          # Application entry point
├── internal/
│   ├── config/          # Configuration management
│   ├── database/        # Database connection
│   ├── handler/         # HTTP handlers
│   ├── middleware/      # Custom middleware
│   ├── models/          # Data models
│   ├── repository/      # Data access layer
│   ├── router/          # Route definitions
│   ├── server/          # HTTP server setup
│   └── service/         # Business logic
├── pkg/
│   ├── errors/          # Error handling utilities
│   └── utils/           # Common utilities
├── db/
│   └── migrations/      # Database migrations
├── build/               # Compiled binaries
└── docker-compose.yml   # Docker setup

🔒 Security

Password Hashing: Bcrypt with configurable cost
Token Authentication: Secure token-based auth system
Input Validation: Request validation on all endpoints
SQL Injection Protection: Parameterized queries with sqlx
Rate Limiting: Configurable via middleware
HTTPS Ready: Deploy behind reverse proxy (Nginx/Traefik)

Security Best Practices

Use strong passwords for database and user accounts
Keep API tokens secure - never commit them to version control
Run behind a reverse proxy with HTTPS in production
Regularly update dependencies and Docker images
Limit database access to the application only
Use firewall rules to restrict access to sensitive ports

🚢 Deployment

Production Deployment

Docker with Reverse Proxy

Nginx Configuration Example:

server {
    listen 80;
    server_name dns.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name dns.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:5010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Environment-Specific Builds

The project supports multiple environments via GitHub Actions:

staging: Deployed on push to staging branch
production: Deployed on push to master branch

Docker images are tagged with:

Semantic version (e.g., 0.0.1)
Commit SHA (e.g., 0.0.1-abc1234)
Environment tag (staging or production)

🧪 Development

Prerequisites

Go 1.24+
PostgreSQL 12+
Make (optional, for taskfile)

Setup Development Environment

Clone and enter directory:

git clone https://github.com/rndmcodeguy20/dyno.git
cd dyno

Install dependencies:
```
go mod download
```

Set up local database:

# Start PostgreSQL (via Docker)
docker run -d \
  --name dyno-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:16-alpine

# Run migrations
psql -h localhost -U postgres -f db/migrations/001_seed.sql

Create .env file:

cp .env.example .env
# Edit with your local configuration

Run the application:
```
go run cmd/server/main.go
```

Building

# Build for current platform
go build -o dyno ./cmd/server/main.go

# Build for Linux
GOOS=linux GOARCH=amd64 go build -o dyno-linux ./cmd/server/main.go

# Build with version info
go build -ldflags="-X 'main.Version=0.0.1'" -o dyno ./cmd/server/main.go

Testing

# Run tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run tests with verbose output
go test -v ./...

🗺️ Roadmap

Current Version (v0.0.1)

✅ Cloudflare DNS integration
✅ User authentication and authorization
✅ Domain CRUD operations
✅ Automatic IP detection
✅ RESTful API
✅ Docker support
✅ CI/CD pipeline

Upcoming Features

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Contribution Guidelines

Follow Go best practices and conventions
Write tests for new features
Update documentation as needed
Keep commits atomic and well-described
Ensure CI/CD pipeline passes

Code Style

This project follows standard Go conventions:

Use gofmt for formatting
Run go vet for static analysis
Follow Effective Go guidelines

🐛 Bug Reports & Feature Requests

Please use GitHub Issues to report bugs or request features:

Bug Report: Describe the issue, steps to reproduce, and expected behavior
Feature Request: Describe the feature and its use case

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Shantanu Mane

Email: hi@rndmcode.in
GitHub: @rndmcodeguy20

🙏 Acknowledgments

Inspired by DuckDNS
Built with Go
Uses Cloudflare Go SDK
Powered by Chi Router

📞 Support

If you find this project helpful, please consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting new features
🤝 Contributing code
📢 Sharing with others

For questions and support, please open an issue on GitHub.

Built with ❤️ by the community

Report Bug • Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.github/workflows		.github/workflows
assets		assets
cmd/server		cmd/server
db/migrations		db/migrations
internal		internal
pkg		pkg
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
README.md		README.md
dockerfile		dockerfile
dyno.toml		dyno.toml
go.mod		go.mod
go.sum		go.sum
openapi.yaml		openapi.yaml
taskfile.yml		taskfile.yml

RndmCodeGuy20/dyno

Folders and files

Latest commit

History

Repository files navigation

Dyno

📖 Overview

Why Dyno?

✨ Features

🚀 Quick Start

Prerequisites

Installation

Option 1: Docker (Recommended)

Option 2: Build from Source

🔧 Configuration

Environment Variables

Getting a Cloudflare API Token

📚 API Reference

Base URL

Authentication

Endpoints

Authentication

Sign Up

Login

Domain Management

List Domains

Create Domain

Update Domain by Name (CLI-Friendly)

Update Domain by ID (RESTful)

Delete Domain

User Profile

Get User Profile

🛠️ Usage Examples

Automated IP Updates with Cron

Python Script

PowerShell Script (Windows)

🏗️ Architecture

Tech Stack

Project Structure

🔒 Security

Security Best Practices

🚢 Deployment

Production Deployment

Docker with Reverse Proxy

Environment-Specific Builds

🧪 Development

Prerequisites

Setup Development Environment

Building

Testing

🗺️ Roadmap

Current Version (v0.0.1)

Upcoming Features

🤝 Contributing

Contribution Guidelines

Code Style

🐛 Bug Reports & Feature Requests

📄 License

👨‍💻 Author

🙏 Acknowledgments

📞 Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages