home/Projects/kompose/docs/content/docs/stacks/code.md

title, description

title	description
<EFBFBD> Code Stack - Your Private GitHub Alternative	Give them Git, make them great!

🦊 Code Stack - Your Private GitHub Alternative

"Give them Git, make them great!" - Some wise developer

What's This All About?

This stack is your personal GitHub - a lightweight, powerful, self-hosted Git service that gives you complete control over your repositories. Gitea is like having GitHub's best features without the Microsoft strings attached!

The Star of the Show

🦊 Gitea

Container: code_app
Image: gitea/gitea:latest
Home: https://git.localhost
SSH: ssh://git@git.localhost:2222

Gitea packs a serious punch for its size:

• 📦 Git Hosting: Unlimited private/public repositories
• 🔀 Pull Requests: Full code review workflow
• 🐛 Issue Tracking: Built-in project management
• 👥 Organizations & Teams: Multi-user collaboration
• 🪝 Webhooks: CI/CD integration ready
• 📝 Wiki: Documentation for your projects
• 🏷️ Releases: Package and distribute your software
• 🔐 Built-in OAuth: Use it as an auth provider!

Configuration Breakdown

Database Connection

All your Git magic is stored in PostgreSQL:

Database: gitea
Host: Shared data stack (postgres)
Connection: Via kompose network

SSH Access

Clone and push repos via SSH on a custom port (2222) to avoid conflicts with the host's SSH:

# Clone example
git clone ssh://git@git.localhost:2222/username/repo.git

# Add remote
git remote add origin ssh://git@git.localhost:2222/username/repo.git

First-Time Setup

On first access, you'll see the installation wizard. Most settings are pre-configured from environment variables!

Environment Variables Explained

Variable	What It Does	Cool Factor
COMPOSE_PROJECT_NAME	Stack identifier	📦 Keeps things organized
DOCKER_IMAGE	Gitea version to use	🏷️ Stay current or pinned
TRAEFIK_HOST	Your domain	🌐 How the world finds you
SSH_PORT	SSH clone port	🔌 Non-standard for safety
APP_PORT	Web interface port	🎯 Internal routing
DB_*	Database connection	🐘 Where memories live

Ports & Networking

• Web Port: 3000 (internal) → 443 (via Traefik)
• SSH Port: 2222 (exposed)
• External Access:
  • Web: https://git.localhost
  • SSH: git@git.localhost:2222
• Network: kompose (the usual gang)

Health & Monitoring

Gitea has built-in health checks:

# Check if Gitea is healthy
docker exec code_app gitea admin check

# View logs
docker logs code_app -f

Getting Started

Initial Configuration (First Run)

1. Start the stack:

   docker compose up -d
   

2. Access the installer:

   URL: https://git.localhost
   

3. Database Settings (pre-filled!):

   • Type: PostgreSQL
   • Host: postgres:5432
   • Database: gitea
   • Username: From root .env
   • Password: From root .env

4. General Settings:

   • Site Title: "My Git Server" (or whatever you like!)
   • SSH Server Port: 2222
   • Base URL: https://git.localhost
   • Email Settings: Inherited from root .env

5. Create Admin Account:

   • Username: admin (or your preference)
   • Email: your@email.com
   • Password: Strong and unique!

6. Install! 🎉

Creating Your First Repository

1. Sign in with your admin account
2. Click the + icon in the top right
3. Select "New Repository"
4. Fill in:
   • Name: my-awesome-project
   • Description: What makes it awesome
   • Visibility: Private or Public
   • Initialize: ✅ Add README, .gitignore, License
5. Create Repository!

Clone & Push

# Clone your new repo
git clone ssh://git@git.localhost:2222/username/my-awesome-project.git
cd my-awesome-project

# Make some changes
echo "# My Awesome Project" >> README.md
git add README.md
git commit -m "Update README"

# Push changes
git push origin main

Common Tasks

Add SSH Key

1. Generate key (if you don't have one):

   ssh-keygen -t ed25519 -C "your@email.com"
   

2. Copy public key:

   cat ~/.ssh/id_ed25519.pub
   

3. In Gitea: Settings → SSH / GPG Keys → Add Key

Create an Organization

1. Click + → New Organization
2. Set name and visibility
3. Invite team members
4. Create team-owned repositories

Set Up Webhooks

1. Go to Repository → Settings → Webhooks
2. Add Webhook (Discord, Slack, or custom URL)
3. Configure events to trigger (push, pull request, etc.)
4. Test the webhook

Enable Actions (CI/CD)

Gitea supports GitHub Actions-compatible workflows!

1. Enable in Admin → Site Administration → Actions
2. Add .gitea/workflows/ to your repo
3. Create workflow YAML files
4. Push and watch them run!

Integration Tips

As OAuth Provider

Gitea can authenticate users for other apps:

1. Create OAuth App: Settings → Applications → Manage OAuth2 Applications
2. Get credentials: Client ID and Secret
3. Configure in your app with these endpoints:
   • Authorization: https://git.localhost/login/oauth/authorize
   • Token: https://git.localhost/login/oauth/access_token
   • User Info: https://git.localhost/api/v1/user

With CI/CD (Semaphore, Jenkins, etc.)

Use webhooks to trigger builds on push:

{
  "url": "https://your-ci-server.com/webhook",
  "content_type": "json",
  "secret": "your-webhook-secret",
  "events": ["push", "pull_request"]
}

Mirror External Repos

Keep a local copy of GitHub/GitLab repos:

1. Create new migration
2. Enter source URL
3. Enable periodic sync

Troubleshooting

Q: Can't clone via SSH?
A: Verify SSH key is added, and use correct port (2222):

git clone ssh://git@git.localhost:2222/username/repo.git

Q: Database connection failed?
A: Check the data stack is running:

docker ps | grep data_postgres

Q: Can't push due to size?
A: Increase client_max_body_size in compose.yaml

Q: Forgot admin password?
A: Reset from CLI:

docker exec code_app gitea admin user change-password --username admin --password newpassword

Security Notes 🔒

• 🔑 SSH Keys: Always use SSH keys, not passwords
• 🔐 Database Credentials: Stored in root .env
• 🌐 HTTPS Only: Traefik handles SSL automatically
• 👥 Private Repos: Default for security
• 🔒 2FA: Enable in user settings for extra security
• 📝 Audit Log: Review in admin panel regularly

Pro Tips 💡

1. Protected Branches: Require reviews before merging to main
2. Git LFS: Enable for large files (models, assets, etc.)
3. Repository Templates: Create templates for consistent project structure
4. Labels & Milestones: Organize issues effectively
5. Project Boards: Kanban-style project management
6. Branch Rules: Enforce naming conventions and workflows
7. Custom .gitignore: Add templates for common languages
8. Release Tags: Use semver for version management

Resources

• Gitea Documentation
• Gitea API Reference
• Community Forums
• Gitea on GitHub

---

"Why use someone else's Git when you can host your own? Take back control, one commit at a time." 🦊✨