Sanitized mirror from private repository - 2026-04-06 09:21:56 UTC
This commit is contained in:
Gitea Mirror Bot
266
docs/getting-started/BEGINNER_QUICKSTART.md
Normal file
266
docs/getting-started/BEGINNER_QUICKSTART.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# 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! 🏠🔬*
|
||||
Reference in New Issue
Block a user