updated docker

how_to_generate_a_repo_from_a_template.md

@@ -0,0 +1,155 @@
+# How to Generate a Repository from a Template in Gitea
+
+## Overview
+
+When working with template repositories in Gitea, you should **NOT** simply clone the template repository directly. Instead, you need to create a **new repository** from the template, which gives you a fresh repository with all the template's content but with its own independent history.
+
+## The Problem
+
+If you just clone a template repository:
+- You're working directly with the template code
+- You don't have your own repository
+- You can't push changes to your own repo
+- The deployment configuration will point to the template repo, not your actual project
+
+## The Solution
+
+Use Gitea's API to generate a new repository from the template.
+
+## Step-by-Step Process
+
+### 1. Create a New Repository from the Template
+
+Use the Gitea API `/repos/{owner}/{repo}/generate` endpoint:
+
+```bash
+curl -X POST "https://git.startanaicompany.com/api/v1/repos/StartanAICompany/ai-recruit-site-template/generate" \
+  -H "Authorization: token YOUR_GITEA_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "owner": "your-username",
+    "name": "your-new-repo-name",
+    "description": "Your project description",
+    "private": false,
+    "git_content": true,
+    "git_hooks": false
+  }'
+```
+
+**Parameters:**
+- `owner`: Your Gitea username (who will own the new repo)
+- `name`: The name for your new repository
+- `description`: Description of your project
+- `private`: Whether the repo should be private (true/false)
+- `git_content`: **Must be true** - copies all the files from the template
+- `git_hooks`: Whether to copy git hooks (usually false)
+
+**Important:** You must include either `git_content: true`, `git_hooks: true`, or `topics: ["something"]` - otherwise you'll get an error: "must select at least one template item"
+
+### 2. Clone Your New Repository
+
+Once created, clone your new repository (not the template):
+
+```bash
+git clone git@git.startanaicompany.com:your-username/your-new-repo-name.git
+```
+
+### 3. Configure Your Project
+
+Navigate into your new repository and configure it:
+
+```bash
+cd your-new-repo-name
+
+# Update .env file with your project details
+cp .env.example .env
+nano .env
+
+# Update GITEA_REPO_NAME to match your new repository name
+# Example:
+# GITEA_USERNAME=your-username
+# GITEA_REPO_NAME=your-new-repo-name
+```
+
+### 4. Deploy
+
+Now you can run the deployment script, which will correctly use your new repository:
+
+```bash
+GITEA_API_TOKEN='your_token' ./deploy-to-apps.sh --register --email your@email.com
+```
+
+## Example: Creating RyanAnderssonRecruit
+
+Here's the actual command used to create the RyanAnderssonRecruit repository:
+
+```bash
+curl -X POST "https://git.startanaicompany.com/api/v1/repos/StartanAICompany/ai-recruit-site-template/generate" \
+  -H "Authorization: token 4fda3793205103bf8c73371342718748d55f4309" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "owner": "ryan.andersson",
+    "name": "ryananderssonrecruit",
+    "description": "RyanAnderssonRecruit - Recruitment site",
+    "private": false,
+    "git_content": true,
+    "git_hooks": false
+  }'
+```
+
+This created a new repository at:
+- **SSH URL:** `git@git.startanaicompany.com:ryan.andersson/ryananderssonrecruit.git`
+- **Web URL:** `https://git.startanaicompany.com/ryan.andersson/ryananderssonrecruit`
+
+## Benefits of Using Templates This Way
+
+1. **Clean History:** Your new repo starts with a fresh commit history
+2. **Independence:** You can modify your repo without affecting the template
+3. **Proper Deployment:** The deployment script will correctly reference your repo, not the template
+4. **Easy Updates:** You can still pull updates from the template if needed
+5. **Multiple Projects:** Create unlimited projects from the same template
+
+## Troubleshooting
+
+### Error: "must select at least one template item"
+
+You forgot to include `git_content: true` in your API request. The API requires at least one of:
+- `git_content: true`
+- `git_hooks: true`
+- `topics: ["something"]`
+
+### The new repo is empty
+
+Make sure you set `git_content: true` in the API request. This copies all files from the template.
+
+### SSH clone not working
+
+Ensure your SSH key is added to Gitea:
+```bash
+curl -X POST "https://git.startanaicompany.com/api/v1/user/keys" \
+  -H "Authorization: token YOUR_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"My SSH Key","key":"ssh-ed25519 AAAA..."}'
+```
+
+## References
+
+- [Gitea Template Repositories Documentation](https://docs.gitea.com/usage/template-repositories)
+- [Gitea API Documentation](https://docs.gitea.com/api/1.22/)
+- [GitHub's approach to templates](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) (similar concept)
+
+## Summary
+
+**Don't:** Clone the template directly
+```bash
+# ❌ Wrong approach
+git clone git@git.startanaicompany.com:StartanAICompany/ai-recruit-site-template.git
+```
+
+**Do:** Create a new repo from the template via API, then clone your new repo
+```bash
+# ✅ Correct approach
+# 1. Create new repo from template (via API)
+# 2. Clone YOUR new repo
+git clone git@git.startanaicompany.com:your-username/your-new-repo-name.git
+```