# Quick Start Guide - 15 Minutes to Forgejo

Get your Forgejo instance running in 15 minutes.

## Prerequisites Check (2 minutes)

```bash
# Install required tools (if not installed)
# macOS:
brew install terraform terragrunt ansible

# Ubuntu/Debian:
sudo apt-get install terraform ansible # (or look for instructions to do this using a virtualenv for ansible)
curl -L https://github.com/gruntwork-io/terragrunt/releases/download/v0.50.0/terragrunt_linux_amd64 -o /usr/local/bin/terragrunt
chmod +x /usr/local/bin/terragrunt

# Verify installations
make check-deps
```

## Step 1: Cloud Provider Setup (3 minutes)

### Option A: Scaleway

1. Create account at https://console.scaleway.com
2. Generate API credentials: Console → IAM → API Keys
3. Export credentials:
  ```bash
  export SCW_ACCESS_KEY="SCW..."
  export SCW_SECRET_KEY="..."
  export SCW_DEFAULT_PROJECT_ID="..." #bear in mind, you might want a project ID other than the default
  ```

### Option B: Hetzner

1. Create account at https://console.hetzner.cloud
2. Generate API token: Security → API Tokens
3. Export token:
  ```bash
  export HCLOUD_TOKEN="..."
  ```

## Step 2: Configuration (5 minutes)

### Configure Domain

```bash
# terraform/scaleway/compute/terraform.tfvars (or hetzner)
domain_name = "git.yourdomain.com"
```

### Generate Secrets

```bash
# Generate strong passwords
openssl rand -base64 32  # Database password
openssl rand -base64 32  # Admin password
openssl rand -base64 48  # Secret key
openssl rand -base64 48  # Internal token
openssl rand -base64 48  # JWT secret
```

### Configure Secrets

```bash
cd ansible/playbooks/vars
cp secrets.yml.example secrets.yml

# Edit with generated passwords
$EDITOR secrets.yml

# Encrypt
ansible-vault encrypt secrets.yml
# Enter vault password (remember this!)
```

### Update Inventory

```bash
$EDITOR ansible/inventory/production/hosts.yml
```

Change:
- `forgejo_domain: git.yourdomain.com`
- `letsencrypt_email: your@email.com`

## Step 3: Deploy (5 minutes)

```bash
# Create infrastructure
make terraform-apply PROVIDER=scaleway  # or hetzner

# Get server IP
make terraform-output PROVIDER=scaleway

# Create DNS A record
# git.yourdomain.com → <server-ip>

# Wait 2 minutes for DNS propagation

# Update inventory with server IP
$EDITOR ansible/inventory/production/hosts.yml
# Change: ansible_host: <your-server-ip>

# Deploy Forgejo
make deploy
# Enter vault password when prompted
```

## Step 4: Access (1 minute)

Visit: `https://git.yourdomain.com`

**First Login:**

1. Complete installation wizard
2. Login with admin credentials from vault
3. Create your first repository!

## Next Steps

- [ ] Configure SSH key: Settings → SSH Keys
- [ ] Create organization
- [ ] Import repositories
- [ ] Set up webhooks
- [ ] Configure CI/CD with Forgejo Actions
- [ ] Invite team members

## Troubleshooting

**Can't connect to server?**

```bash
make ansible-ping
```

**SSL certificate not working?**
- Wait 5 minutes for Let's Encrypt
- Check DNS: `dig git.yourdomain.com`

**Service not starting?**

```bash
make logs
make status
```

**Need to start over?**

```bash
make terraform-destroy PROVIDER=scaleway
# Then start from Step 3
```

## Daily Operations

```bash
# Create backup
make backup

# Update Forgejo
make update

# View logs
make logs

# SSH into server
make ssh

# Check health
make health
```

## Cost Per Month (in January 2026)

- **Scaleway**: ~€9/month
- **Hetzner**: ~€8/month

**vs GitHub Enterprise**: €19/user/month

## Support

- Check logs: `make logs`
- View status: `make status`
- Full docs: `README.md`
- Troubleshooting: `README.md#troubleshooting`

---

That's it! You now have a production-ready Forgejo instance running on European infrastructure. 🎉