homelab-optimized/docs/getting-started/BEGINNER_QUICKSTART.md

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:

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)

# 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:

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
• Portainer Documentation
• Your homelab's DEVELOPMENT.md

Finding Services

• Docker Hub - Official Docker images
• LinuxServer.io - Well-maintained homelab images
• 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! 🏠🔬