Skip to content

Setup Guide

This guide walks you through installing and configuring Tinkero on your server.

Table of Contents

  1. Prerequisites
  2. Prerequisite Validation
  3. Installation
  4. DNS Configuration
  5. Running Setup
  6. Port Requirements
  7. Firewall Configuration
  8. Troubleshooting

Prerequisites

Required Software

Software Minimum Version Check Command
Docker 20.10+ docker --version
Docker Compose 2.0+ docker compose version
Git 2.0+ git --version

System Requirements

Resource Minimum Recommended
RAM 2 GB 4 GB
CPU 1 core 2 cores
Disk 10 GB 20 GB+
OS Linux (Ubuntu 20.04+) Ubuntu 22.04 LTS

Network Requirements

  • A domain name (e.g., tinkero.example.com)
  • Cloudflare account with domain DNS managed by Cloudflare (required for SSL certificates)
  • DNS pointing to your server's IP address
  • Ports 80 and 443 available (not used by other services)
  • Outbound HTTPS access (for GitHub API and Let's Encrypt)

Why Cloudflare is Required

Tinkero uses Cloudflare DNS-01 challenge for Let's Encrypt SSL certificates. This provides several benefits:

  • Works behind NAT: No need for your server to be directly accessible from the internet on port 80
  • No port forwarding required: SSL certificates can be obtained without incoming HTTP traffic
  • Wildcard certificate support: Single certificate for all subdomains
  • More reliable: DNS-01 doesn't require your web server to be running during certificate renewal

Alternative: If you cannot use Cloudflare, you can modify docker-compose.yml to use HTTP-01 challenge instead (requires ports 80/443 publicly accessible).

Prerequisite Validation

Before running setup, validate your environment using the tinkero setup command's built-in checks, or manually verify each requirement:

Docker Check

# Check Docker is installed and running
docker --version
# Expected: Docker version 20.10.x or higher

# Verify Docker daemon is running
docker info
# Should display system information without errors

# Verify you can run containers
docker run hello-world
# Should complete successfully

Docker Compose Check

# Check Docker Compose version (v2 syntax)
docker compose version
# Expected: Docker Compose version v2.x.x

# Alternative (legacy syntax)
docker-compose --version

Port Availability

# Check if ports 80 and 443 are available
sudo lsof -i :80
sudo lsof -i :443
# Both commands should return empty (no output)

# Alternative using netstat
sudo netstat -tlnp | grep -E ':80|:443'
# Should return empty

Disk Space

# Check available disk space
df -h /
# Ensure at least 10 GB available

# Check where Docker stores data
docker system df

Installation

Option 1: Download Pre-built Binary

# Linux (amd64)
wget https://github.com/yourusername/tinkero/releases/latest/download/tinkero-linux-amd64
chmod +x tinkero-linux-amd64
sudo mv tinkero-linux-amd64 /usr/local/bin/tinkero

# Verify installation
tinkero --help

Option 2: Build from Source

# Clone the repository
git clone https://github.com/yourusername/tinkero.git
cd tinkero

# Build the CLI
cd cmd/tinkero
go build -o tinkero .

# Install globally
sudo mv tinkero /usr/local/bin/

# Return to project root
cd ../..

Option 3: Build All Platforms

cd cmd/tinkero
./build.sh
# Binaries will be in bin/ directory

DNS Configuration

Step 1: Transfer Domain to Cloudflare

Tinkero requires your domain to be managed by Cloudflare:

  1. Sign up for Cloudflare: Visit cloudflare.com and create a free account
  2. Add your domain: Click "Add a Site" and enter your domain name
  3. Update nameservers: Cloudflare will provide nameservers (e.g., ava.ns.cloudflare.com)
  4. Log in to your domain registrar (GoDaddy, Namecheap, etc.)
  5. Update nameservers to point to Cloudflare
  6. Wait for propagation (can take 24-48 hours)

Step 2: Create DNS Records

Create an A record pointing your domain to your server's IP:

Type Name Value Proxy Status TTL
A tinkero YOUR_SERVER_IP DNS only (grey) Auto

Important: Set to "DNS only" (grey cloud), not proxied (orange cloud).

Step 3: Create Cloudflare API Token

The DNS-01 challenge requires a Cloudflare API token:

  1. Navigate to API Tokens:
  2. Go to Cloudflare dashboard
  3. Click your profile icon (top right)

  4. Select My Profile → API Tokens

  5. Create Token:

  6. Click Create Token
  7. Use the Edit zone DNS template

  8. Or create custom token with these permissions:

    • Zone → DNS → Edit
    • Zone → Zone → Read

  9. Configure Token Scope:

  10. Zone Resources: Include → Specific zone → Select your domain

  11. Click Continue to summary

  12. Create and Save Token:

  13. Click Create Token
  14. Copy the token immediately (it won't be shown again)
  15. Save it securely - you'll need it during setup

Step 4: DNS Verification

# Verify DNS propagation
dig +short tinkero.example.com
# Should return your server's IP

# Alternative
nslookup tinkero.example.com

# Verify nameservers point to Cloudflare
dig NS tinkero.example.com
# Should show Cloudflare nameservers

SSL/TLS Configuration in Cloudflare

After setup completes:

  1. SSL/TLS Mode: Set to Full (strict) in Cloudflare dashboard
  2. Navigate to SSL/TLS → Overview

  3. Select Full (strict)

  4. Enable Proxy (Optional): After SSL certificates are working

  5. Return to DNS settings
  6. Click the grey cloud to enable proxy (orange cloud)
  7. This adds Cloudflare's CDN and DDoS protection

Running Setup

Interactive Setup Wizard

# Navigate to the Tinkero directory
cd /path/to/tinkero

# Run the setup wizard
tinkero setup

Setup Process

The setup wizard performs the following steps:

Step 1: Prerequisite Validation

🚀 Starting Tinkero Setup Wizard

ℹ️  Step 1/5: Validating prerequisites...

=== Prerequisite Validation Results ===

✅ Docker Version Check
   Version: 24.0.7 (required: 20.10+)

✅ Docker Daemon Check
   Status: Running

✅ Docker Compose Check
   Version: 2.21.0 (required: 2.0+)

✅ Port Availability Check
   Port 80: Available
   Port 443: Available

✅ Disk Space Check
   Available: 45 GB at '/' (required: 10 GB)

✅ Tinkero Directory Check
   Found: docker-compose.yml

Step 2: Configuration Collection

You'll be prompted for:

Setting Description Example
Domain name Your server's domain (must be on Cloudflare) tinkero.example.com
ACME email Email for Let's Encrypt certificate notifications admin@example.com
Cloudflare API token Required for DNS-01 challenge y_QcjL... (from Cloudflare dashboard)
Traefik username Dashboard login admin
Traefik password Dashboard password (min 12 chars) (secure password)

Important: Have your Cloudflare API token ready before running setup. See DNS Configuration for instructions.

Step 3: Configuration File Generation

The wizard creates a .env file with your settings:

# Generated .env file location
cat .env

Step 4: Service Startup

Docker Compose pulls images and starts all services:

ℹ️  Step 4/5: Starting Tinkero services...
⚠️  This may take several minutes on first run...

[+] Running 7/7
 ✔ Container traefik         Started
 ✔ Container caddy           Started
 ✔ Container redis           Started
 ✔ Container webhook-handler Started
 ✔ Container prometheus      Started
 ✔ Container loki            Started

Step 5: Next Steps

The wizard displays instructions for completing GitHub App configuration.

Port Requirements

External Ports (Must Be Open)

Port Protocol Service Required
80 TCP Traefik (HTTP) Yes
443 TCP Traefik (HTTPS) Yes
22 TCP SSH Recommended

Internal Ports (Docker Network Only)

Port Service Purpose
2019 Caddy Admin API
3100 Loki Log aggregation
6379 Redis Metadata store
8080 Webhook Handler HTTP API
8082 Traefik Metrics
9090 Prometheus Metrics storage

Important: Internal ports should NOT be exposed to the internet. Access them via SSH tunnel.

Firewall Configuration

UFW (Ubuntu)

# Allow SSH
sudo ufw allow 22/tcp

# Allow HTTP and HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Enable firewall
sudo ufw enable

# Verify rules
sudo ufw status verbose

iptables

# Allow established connections
sudo iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Allow SSH
sudo iptables -A INPUT -p tcp --dport 22 -j ACCEPT

# Allow HTTP and HTTPS
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# Drop everything else
sudo iptables -A INPUT -j DROP

# Save rules (Ubuntu)
sudo netfilter-persistent save

Cloud Provider Firewalls

If using a cloud provider, also configure the security group/firewall:

AWS Security Group: - Inbound: TCP 22, 80, 443 from 0.0.0.0/0 - Outbound: All traffic

DigitalOcean Firewall: - Inbound: SSH (22), HTTP (80), HTTPS (443) - Outbound: All TCP, All UDP

Google Cloud Firewall: - Allow tcp:22,80,443 from 0.0.0.0/0

Troubleshooting

Docker Issues

Docker not installed: 

# Install Docker (Ubuntu)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

Docker daemon not running: 

# Start Docker
sudo systemctl start docker

# Enable Docker on boot
sudo systemctl enable docker

# Check status
sudo systemctl status docker

Permission denied: 

# Add current user to docker group
sudo usermod -aG docker $USER

# Apply new group membership
newgrp docker

# Or log out and back in

Port Conflicts

Port 80 in use: 

# Find what's using port 80
sudo lsof -i :80
# or
sudo netstat -tlnp | grep :80

# Common culprits:
# - Apache: sudo systemctl stop apache2
# - Nginx: sudo systemctl stop nginx

Port 443 in use: 

# Find what's using port 443
sudo lsof -i :443

# Stop the conflicting service
sudo systemctl stop <service-name>

DNS Issues

DNS not resolving: 

# Check if DNS has propagated
dig +short yourdomain.com

# Check from different DNS servers
dig @8.8.8.8 +short yourdomain.com
dig @1.1.1.1 +short yourdomain.com

SSL certificate issues: - Verify Cloudflare API token is valid: Test at Cloudflare API - Check domain is on Cloudflare: Verify nameservers with dig NS yourdomain.com - Ensure DNS records exist: Domain must have A record before requesting certificate - Check Traefik logs: docker compose logs traefik | grep acme - Verify ACME email is correct in .env - Wait for DNS propagation: Can take up to 48 hours after changing nameservers - Check token permissions: Must have Zone:DNS:Edit and Zone:Zone:Read

Token validation: 

# Test Cloudflare API token
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"

# Should return: {"result":{"id":"...","status":"active",...},"success":true}

Disk Space Issues

Insufficient space: 

# Check disk usage
df -h

# Clean Docker resources
docker system prune -a

# Remove unused volumes
docker volume prune

# Clean old Tinkero releases
tinkero cleanup

Setup Fails to Start Services

# Check Docker Compose logs
docker compose logs

# Check specific service
docker compose logs traefik
docker compose logs webhook-handler

# Restart all services
docker compose down
docker compose up -d

# Rebuild and restart
docker compose up -d --build

Environment File Issues

.env backup location: If setup finds an existing .env, it creates a backup: 

# Backup is at:
ls -la .env.backup

# Restore if needed:
cp .env.backup .env

Reset configuration: 

# Remove existing .env and run setup again
rm .env
tinkero setup

Next Steps

After completing setup:

  1. Configure GitHub App: Follow the GitHub App Guide
  2. Verify Health: Run tinkero health
  3. Access Dashboards:
  4. Traefik: https://lair.nntin.xyz/traefik
  5. Dashboards: central Grafana (master stack)
  6. Deploy Your First Site: Add .tinkero.yml to a repository

Need help? Check the Troubleshooting Guide or open an issue.