Horacio Duran
822e42dbb8
This template allows deploying a forgejo en either Scaleway or Hetzner (untested) without much knowledge about them. It DOES require knowledge about Terragrunt and ansible. A wizard of sorts is provided but it will not guarantee success without some knowledge about the underlying technology.
190 lines
3.7 KiB
Markdown
190 lines
3.7 KiB
Markdown
# 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. 🎉
|