# Beginner's Quick Start Guide

**New to homelabs?** This guide walks you through deploying your first service step-by-step.

## 🎯 What You'll Learn

By the end of this guide, you'll know how to:
- Access your homelab tools (Gitea, Portainer)
- Deploy a simple service
- Understand the basic workflow
- Troubleshoot common issues

## 📋 Before You Start

### What You Need
- [ ] **Computer with internet access**
- [ ] **Web browser** (Chrome, Firefox, Safari, etc.)
- [ ] **Text editor** (Notepad++, VS Code, or even basic Notepad)
- [ ] **Basic understanding** of copy/paste and file editing

### What You DON'T Need
- Advanced programming knowledge
- Command line experience (we'll show you the easy way)
- Docker expertise

## 🚀 Step-by-Step: Deploy Your First Service

### Step 1: Access Your Tools

#### Gitea (Your Code Repository)
1. Open your web browser
2. Go to `https://git.vish.gg` (or your Gitea URL)
3. Log in with your credentials
4. Navigate to the `homelab` repository

#### Portainer (Your Container Manager)
1. Open a new browser tab
2. Go to your Portainer URL (usually `https://portainer.yourdomain.com`)
3. Log in with your credentials
4. You should see the Portainer dashboard

### Step 2: Choose What to Deploy

**For your first deployment, let's use a simple service like:**
- **Uptime Kuma** - Website monitoring
- **IT Tools** - Handy web utilities
- **Stirling PDF** - PDF manipulation tools

**We'll use IT Tools as our example.**

### Step 3: Create Your Service File

#### Option A: Using Gitea Web Interface (Easiest)

1. **In Gitea**, navigate to your homelab repository
2. **Choose your server location**:
   - Click on `hosts/` folder
   - Click on your server type (e.g., `synology/`)
   - Click on your server name (e.g., `atlantis/`)
3. **Create new file**:
   - Click the "+" button or "New File"
   - Name it: `it-tools.yml`
4. **Copy this configuration**:

```yaml
version: '3.8'

services:
  it-tools:
    image: corentinth/it-tools:latest
    container_name: it-tools
    restart: unless-stopped
    ports:
      - "8080:80"  # Change 8080 if this port is already used
    networks:
      - homelab

networks:
  homelab:
    external: true
```

5. **Save the file**:
   - Add a commit message: "Add IT Tools service"
   - Click "Commit Changes"

#### Option B: Using Git (If You're Comfortable)

```bash
# Clone the repository
git clone https://git.vish.gg/Vish/homelab.git
cd homelab

# Create the file
nano hosts/synology/atlantis/it-tools.yml
# (Copy the YAML content above)

# Save and commit
git add hosts/synology/atlantis/it-tools.yml
git commit -m "Add IT Tools service"
git push
```

### Step 4: Deploy via Portainer

1. **In Portainer**, go to "Stacks" (left sidebar)
2. **Click "Add stack"**
3. **Fill in the details**:
   - **Name**: `it-tools`
   - **Build method**: Select "Repository"
   - **Repository URL**: `https://git.vish.gg/Vish/homelab`
   - **Repository reference**: `refs/heads/main`
   - **Compose path**: `hosts/synology/atlantis/it-tools.yml`
   - **Automatic updates**: Check this box (optional)
4. **Click "Deploy the stack"**
5. **Wait for deployment** - You'll see logs showing the progress

### Step 5: Access Your Service

1. **Find your server's IP address** (e.g., 192.168.1.100)
2. **Open your browser** and go to: `http://192.168.1.100:8080`
3. **You should see IT Tools running!**

## 🎉 Congratulations!

You just deployed your first homelab service! Here's what happened:

1. **You created** a Docker Compose file describing your service
2. **Gitea stored** your configuration safely
3. **Portainer read** the configuration from Gitea
4. **Docker deployed** your service automatically

## 🔧 Understanding Your Setup

### The Files You Work With

```
homelab/
├── hosts/                    # Server configurations
│   ├── synology/atlantis/    # Your main NAS
│   ├── synology/calypso/     # Your backup NAS
│   ├── vms/homelab-vm/       # Your virtual machines
│   └── physical/concord-nuc/ # Your physical servers
├── docs/                     # Documentation (like this guide)
└── scripts/                  # Helpful automation scripts
```

### The Tools Working Together

1. **Gitea** = Your filing cabinet (stores all configurations)
2. **Portainer** = Your deployment assistant (reads from Gitea and deploys)
3. **Docker** = Your service runner (actually runs the applications)

### The Workflow

```
You edit file → Gitea stores it → Portainer deploys it → Service runs
```

## 🛠️ Common Tasks

### Deploy Another Service

1. **Find an example** in the existing files
2. **Copy and modify** it for your needs
3. **Change the ports** to avoid conflicts
4. **Deploy via Portainer** using the same steps

### Update a Service

1. **Edit the YAML file** in Gitea
2. **Commit your changes**
3. **In Portainer**, go to your stack and click "Update"
4. **Portainer will redeploy** with your changes

### Remove a Service

1. **In Portainer**, go to "Stacks"
2. **Find your service** and click the trash icon
3. **Confirm deletion**
4. **Optionally delete** the YAML file from Gitea

## 🚨 Troubleshooting

### "Port already in use" Error

**Problem**: Another service is using the same port.

**Solution**: Change the port in your YAML file:
```yaml
ports:
  - "8081:80"  # Changed from 8080 to 8081
```

### "Cannot access service" Error

**Checklist**:
- [ ] Is the service running? (Check Portainer → Stacks)
- [ ] Are you using the right IP address?
- [ ] Are you using the right port number?
- [ ] Is your firewall blocking the port?

### "Deployment failed" Error

**Common causes**:
- **YAML syntax error** - Check indentation (use spaces, not tabs)
- **Invalid image name** - Verify the Docker image exists
- **Volume path doesn't exist** - Create the directory first

### Getting Help

1. **Check the logs** in Portainer (Stacks → Your Stack → Logs)
2. **Look at similar services** in the repository for examples
3. **Check the service documentation** on Docker Hub

## 📚 Next Steps

### Learn More About Docker Compose

**Key concepts to understand**:
- **Services** - The applications you run
- **Ports** - How to access services from outside
- **Volumes** - Where data is stored
- **Networks** - How services talk to each other

### Explore Advanced Features

- **Environment variables** for configuration
- **Multiple services** in one file
- **Service dependencies** and startup order
- **Resource limits** and health checks

### Popular Services to Try

**Media Management**:
- Plex/Jellyfin (media server)
- Sonarr/Radarr (media automation)
- Overseerr (media requests)

**Productivity**:
- Nextcloud (file sync)
- Bitwarden (password manager)
- Paperless-ngx (document management)

**Monitoring**:
- Uptime Kuma (uptime monitoring)
- Grafana (dashboards)
- Portainer Agent (container monitoring)

## 🔗 Useful Resources

### Documentation
- [Docker Compose Reference](https://docs.docker.com/compose/)
- [Portainer Documentation](https://docs.portainer.io/)
- [Your homelab's DEVELOPMENT.md](DEVELOPMENT.md)

### Finding Services
- [Docker Hub](https://hub.docker.com/) - Official Docker images
- [LinuxServer.io](https://docs.linuxserver.io/) - Well-maintained homelab images
- [Awesome-Selfhosted](https://github.com/awesome-selfhosted/awesome-selfhosted) - Huge list of self-hosted services

---

**Remember**: Start simple, learn as you go, and don't be afraid to experiment! Your homelab is a safe place to try new things.

*Happy homelabbing! 🏠🔬*