Frequently Asked Questions¶

Common questions and answers about using Tinkero.

Table of Contents¶

Getting Started
Configuration
Deployment
Maintenance
Troubleshooting

Getting Started¶

How do I add a new site to Tinkero?¶

Install the GitHub App on your repository:
Go to https://github.com/apps/YOUR-APP-NAME/installations/new
Select your repository
Add .tinkero.yml to your repository root:
```
branch: main
outputDir: dist
```
Push to your repository - Tinkero will automatically build and deploy.

What permissions does the GitHub App need?¶

Permission	Level	Purpose
Contents	Read	Clone repositories
Deployments	Read/Write	Update deployment status
Metadata	Read	Repository information

Events to subscribe: - Push

See: GitHub App Guide

How do I access Grafana?¶

Use the central Grafana instance (master stack). Tinkero dashboards are provisioned under the Tinkero folder.

See: Monitoring Guide

Configuration¶

How do I change the deployment path for my site?¶

The deployment path is determined by your repository's owner/name. Currently, you cannot customize the path in .tinkero.yml.

To change the path: 1. Create a new repository with the desired name 2. Remove the old site (see How do I delete a site?) 3. Push to the new repository

How do I deploy a site without running a build?¶

Use skipBuild: true in your .tinkero.yml:

branch: main
outputDir: public
skipBuild: true

This is useful for: - Static HTML/CSS/JS sites - Pre-built sites committed to the repository - Sites built by external CI/CD

See: Configuration Reference

How do I set environment variables for my build?¶

Add the env field to .tinkero.yml:

branch: main
outputDir: dist
env:
  NODE_ENV: production
  API_URL: https://api.example.com
  ENABLE_ANALYTICS: "true"  # Quote booleans and numbers

Note: Environment variables are only available during build, not at runtime.

See: Configuration Reference

Can I deploy from multiple branches?¶

Currently, each .tinkero.yml can only specify one branch. Options:

Single branch deployment (default):
```
branch: main
```
Only pushes to main trigger deployments. This is also the default if branch is omitted.
All branches (explicit):
```
branch: ""
outputDir: dist
```
Explicitly set branch: "" to deploy from every branch.
Separate repositories: For staging/production, use separate repositories or branches with different Tinkero instances.

How do I use a different Node.js version?¶

Specify nodeVersion in .tinkero.yml:

branch: main
outputDir: dist
nodeVersion: "20"  # Always quote the version

Available versions depend on Docker images. Common versions: "16", "18", "20".

See: Configuration Reference

Deployment¶

How do I trigger a manual deployment?¶

Push an empty commit to trigger a deployment:

git commit --allow-empty -m "Trigger deployment"
git push

Or use GitHub's "Re-run" feature on a recent webhook delivery: 1. Go to GitHub App settings > Advanced > Recent Deliveries 2. Find a previous webhook 3. Click "Redeliver"

How do I view build logs?¶

Via command line:

docker compose logs -f webhook-handler

Via Central Grafana (Loki): 1. Open the central Grafana instance 2. Go to Explore > Select Loki 3. Query:

{container_name="webhook-handler"} |= "deployment"

See: Monitoring Guide

Why isn't my deployment triggering?¶

Check these common causes:

Branch filter: If .tinkero.yml specifies branch: main, pushes to other branches are ignored.
App not installed: Verify the GitHub App is installed on the repository.
Webhook URL: Check the webhook URL in GitHub App settings is correct.
Webhook secret: Verify the secret matches between GitHub and Tinkero.

Debug steps:

# Check webhook-handler logs
docker compose logs --tail 100 webhook-handler

# Check GitHub webhook deliveries
# Go to: GitHub App settings > Advanced > Recent Deliveries

See: Troubleshooting

How do I handle builds that take too long?¶

Tinkero has default timeouts for builds. For long builds:

Optimize your build:
Use npm ci instead of npm install
Enable build caching
Remove unused dependencies
Use pre-built sites:
```
skipBuild: true
outputDir: dist
```
Build locally or in CI/CD and commit the built files.

See: Troubleshooting

What happens if a build fails?¶

When a build fails: 1. GitHub Deployment status is set to "failure" 2. An error page is generated at the site URL 3. The previous successful deployment remains active (zero-downtime)

The error page shows: - Commit hash - Error message - Timestamp

See: Troubleshooting

Maintenance¶

How do I clean up old releases?¶

Use the tinkero cleanup command:

# Interactive mode
tinkero cleanup

# Specific site
tinkero cleanup my-site

This shows all releases and lets you delete selected ones or all old releases.

See: CLI Reference

How do I monitor disk space?¶

Via command line:

# Overall disk usage
df -h /

# Tinkero sites usage
du -sh /srv/tinkero/sites/*

Via Central Grafana: 1. Open the central Grafana instance 2. Navigate to the System dashboard 3. Check the "Disk Usage" panel

See: Operations Guide

How do I delete a site?¶

Site deletion is currently a manual process:

# 1. Remove site directory
sudo rm -rf /srv/tinkero/sites/my-site/

# 2. Remove from Redis
docker exec redis redis-cli DEL "site:my-site"

# 3. Reload Caddy (may be automatic)
docker compose restart caddy

Note: This is destructive and cannot be undone. Back up first if needed.

See: Operations Guide

How do I backup Tinkero?¶

Backup these components:

Component	Location	Priority
Configuration	`.env`	Critical
GitHub App key	`/srv/tinkero/github-app-key.pem`	Critical
SSL certificates	`./data/acme.json`	High
Site content	`/srv/tinkero/sites/`	Medium

Backup command:

mkdir -p ~/tinkero-backup
cp .env ~/tinkero-backup/
cp /srv/tinkero/github-app-key.pem ~/tinkero-backup/
cp data/acme.json ~/tinkero-backup/
tar -czf ~/tinkero-backup/sites.tar.gz /srv/tinkero/sites/

See: Operations Guide

How do I update Tinkero?¶

# Pull latest changes
cd /path/to/tinkero
git pull origin main

# Rebuild and restart
docker compose pull
docker compose build --no-cache webhook-handler
docker compose up -d

# Verify
tinkero health

See: Operations Guide

Troubleshooting¶

Why does `tinkero health` show services as unhealthy?¶

Common causes:

Services not started:
```
docker compose up -d
```
Docker not running:
```
sudo systemctl start docker
```

Resource issues:

free -h  # Check memory
df -h    # Check disk

See: Troubleshooting

Why is my site showing a 404 error?¶

Check these issues:

Deployment didn't complete:

ls -la /srv/tinkero/sites/my-site/current/

Wrong output directory: Verify outputDir in .tinkero.yml matches your build output.
Build produced empty output: Check build logs for errors.

See: Troubleshooting

Why is SSL not working?¶

Common causes:

Cloudflare token invalid or missing:
```
# Verify token is set in .env
grep CLOUDFLARE_DNS_API_TOKEN .env
```
Tinkero uses DNS-01 challenge which requires a valid Cloudflare API token.
Domain not on Cloudflare:
```
# Check nameservers
dig NS yourdomain.com
# Should show *.ns.cloudflare.com
```
Your domain must be managed by Cloudflare for SSL to work.
DNS not propagated:
```
dig +short yourdomain.com
```
Wait up to 48 hours after changing nameservers to Cloudflare.
Rate limited: Too many certificate requests. Wait 1 hour and check Let's Encrypt status.

See: Troubleshooting for detailed diagnostics.

How do I reset everything and start fresh?¶

# Stop all services
docker compose down

# Remove all containers and volumes
docker compose down -v

# Remove configuration
rm .env

# Remove site data (careful!)
sudo rm -rf /srv/tinkero/sites/*

# Re-run setup
tinkero setup

Warning: This destroys all data. Backup first!

Where can I get help?¶

Documentation:
Setup Guide
Troubleshooting
CLI Reference
Health Check:
```
tinkero health
```
Logs:
```
docker compose logs -f
```
Issues: Open an issue on GitHub with:
Error message
tinkero health output
Relevant logs

Quick Reference¶

Common Commands¶

Task	Command
Check health	`tinkero health`
View logs	`docker compose logs -f`
Restart services	`docker compose restart`
Clean up releases	`tinkero cleanup`
Configure GitHub	`tinkero config`

Important Files¶

File	Purpose
`.env`	Configuration
`docker-compose.yml`	Service definitions
`/srv/tinkero/sites/`	Deployed sites
`data/acme.json`	SSL certificates

Service Ports¶

Port	Service	Access
80	Traefik (HTTP)	Public
443	Traefik (HTTPS)	Public
9090	Prometheus	SSH tunnel
3100	Loki	SSH tunnel

Still have questions? Open an issue on GitHub!

Frequently Asked Questions¶

Table of Contents¶

Getting Started¶

How do I add a new site to Tinkero?¶

What permissions does the GitHub App need?¶

How do I access Grafana?¶

Configuration¶

How do I change the deployment path for my site?¶

How do I deploy a site without running a build?¶

How do I set environment variables for my build?¶

Can I deploy from multiple branches?¶

How do I use a different Node.js version?¶

Deployment¶

How do I trigger a manual deployment?¶

How do I view build logs?¶

Why isn't my deployment triggering?¶

How do I handle builds that take too long?¶

What happens if a build fails?¶

Maintenance¶

How do I clean up old releases?¶

How do I monitor disk space?¶

How do I delete a site?¶

How do I backup Tinkero?¶

How do I update Tinkero?¶

Troubleshooting¶

Why does tinkero health show services as unhealthy?¶

Why is my site showing a 404 error?¶

Why is SSL not working?¶

How do I reset everything and start fresh?¶

Where can I get help?¶

Quick Reference¶

Common Commands¶

Important Files¶

Service Ports¶

Why does `tinkero health` show services as unhealthy?¶