{"id":33918349,"url":"https://github.com/ipedro/moonbase","last_synced_at":"2026-03-11T19:31:35.634Z","repository":{"id":325824937,"uuid":"1102511081","full_name":"ipedro/moonbase","owner":"ipedro","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-06T02:35:02.000Z","size":20,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-08T11:56:52.592Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ipedro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-23T15:41:01.000Z","updated_at":"2025-12-06T02:35:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ipedro/moonbase","commit_stats":null,"previous_names":["ipedro/moonbase"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ipedro/moonbase","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipedro%2Fmoonbase","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipedro%2Fmoonbase/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipedro%2Fmoonbase/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipedro%2Fmoonbase/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ipedro","download_url":"https://codeload.github.com/ipedro/moonbase/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ipedro%2Fmoonbase/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30395597,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T18:46:22.935Z","status":"ssl_error","status_checked_at":"2026-03-11T18:46:17.045Z","response_time":84,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-12T08:18:38.496Z","updated_at":"2026-03-11T19:31:35.628Z","avatar_url":"https://github.com/ipedro.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Moonbase 🌙\n\nRemote Raspberry Pi 4 satellite deployment for VPN exit node at parents' location.\n\n## Hardware\n\n- **Raspberry Pi 4 (4GB RAM)**\n- Location: Parents' home network\n- Purpose: VPN exit node for geo-restricted services\n\n## 🚀 Installation\n\n### Quick Start\nRun this on the Raspberry Pi:\n```bash\n# Clone and run setup (prompts for GitHub credentials if private)\ngit clone https://github.com/ipedro/moonbase.git ~/Developer/moonbase \u0026\u0026 ~/Developer/moonbase/setup.sh\n```\n\n### Manual Installation\n1. Clone the repo: `git clone https://github.com/ipedro/moonbase.git`\n2. Run Setup: `./setup.sh`\n\n- **[WireGuard](https://www.wireguard.com/)**: VPN server for secure remote access\n  - Port: 51820/udp\n  - Generates peer configs automatically\n  - Routes all traffic through parents' connection\n  \n- **[Cloudflare DDNS](https://github.com/oznu/docker-cloudflare-ddns)**: Dynamic DNS updater\n  - Updates `moonbase.yourdomain.com` with current IP\n  - No port forwarding setup needed on their router\n  \n- **[Watchtower](https://containrrr.dev/watchtower/)**: Automatic container updates\n  - Runs daily at 3 AM\n  - Keeps all services up-to-date\n  \n- **[Portainer Agent](https://www.portainer.io/)**: Remote management\n  - Port: 9001\n  - Connect from homelab Portainer for remote administration\n  \n- **[Node Exporter](https://github.com/prometheus/node_exporter)**: System metrics\n  - Exports metrics for Prometheus scraping from homelab\n  - Monitor Pi health remotely\n\n- **[Code Server](https://github.com/coder/code-server)**: Web-based VS Code\n  - Port: 8443\n  - Full IDE access via browser\n  - Edit configs, check logs, debug remotely\n  \n- **[GitHub Actions Runner](https://github.com/myoung34/docker-github-actions-runner)**: Self-hosted CI/CD\n  - Automatic deployments on git push\n  - No SSH needed for updates\n\n## Setup\n\n### Prerequisites\n\n- Raspberry Pi 4 with Raspberry Pi OS (64-bit recommended)\n- Docker and Docker Compose installed\n- Cloudflare account with API token\n- Port forwarding on parents' router: **51820/udp → Pi local IP**\n\n### Installation\n\n1. **Clone repository on the Pi:**\n   ```bash\n   git clone https://github.com/ipedro/moonbase.git /home/pi/moonbase\n   cd /home/pi/moonbase\n   ```\n\n2. **Configure environment:**\n   ```bash\n   cp .env.example .env\n   nano .env\n   ```\n   \n   Update with your Cloudflare credentials:\n   ```\n   CLOUDFLARE_API_TOKEN=your_api_token\n   CLOUDFLARE_ZONE=yourdomain.com\n   CODE_SERVER_PASSWORD=secure_password_here\n   GITHUB_PAT=your_github_personal_access_token\n   ```\n\n3. **Start services:**\n   ```bash\n   docker compose up -d\n   ```\n\n4. **Get WireGuard client configs:**\n   ```bash\n   # Configs are generated in wireguard/config/\n   # QR codes for mobile devices:\n   docker exec wireguard /app/show-peer 1\n   docker exec wireguard /app/show-peer 2\n   # etc.\n   ```\n\n### Router Configuration\n\n**Option 1: UPnP (Automatic - Recommended if available)**\n\nTest if router supports UPnP:\n```bash\nbash scripts/test-upnp.sh\n```\n\nIf supported, the `setup.sh` script will offer to enable automatic port forwarding.\nNo manual router configuration needed!\n\n**Option 2: Manual Port Forwarding**\n\nIf UPnP is not available or you prefer manual control:\n\n**Port forwarding required:**\n- External Port: 51820 (UDP)\n- Internal Port: 51820 (UDP)\n- Internal IP: Pi's local IP (e.g., 192.168.1.100)\n\n**Find Pi's local IP:**\n```bash\nhostname -I | awk '{print $1}'\n```\n\n## WireGuard Client Setup\n\n### Desktop (Linux/macOS/Windows)\n\n1. **Copy config file from Pi:**\n   ```bash\n   scp pi@moonbase-ip:/home/pi/moonbase/wireguard/config/peer1/peer1.conf ~/wireguard-moonbase.conf\n   ```\n\n2. **Import into WireGuard app:**\n   - Install WireGuard from official site\n   - Import configuration file\n   - Connect!\n\n### Mobile (iOS/Android)\n\n1. **Generate QR code on Pi:**\n   ```bash\n   docker exec wireguard /app/show-peer 1\n   ```\n\n2. **Scan with WireGuard app:**\n   - Install WireGuard from App Store/Play Store\n   - Add tunnel → Scan QR code\n   - Connect!\n\n## Usage\n\n### Connect to VPN\n\nOnce connected to WireGuard:\n- All your traffic routes through parents' internet connection\n- Appears as local citizen for geo-restricted services\n- Access parents' local network devices (if needed)\n\n### Split Tunneling (Optional)\n\nTo route only specific traffic through the VPN, edit your peer config:\n\n```ini\n# Instead of:\nAllowedIPs = 0.0.0.0/0\n\n# Use specific routes:\nAllowedIPs = 192.168.1.0/24  # Parents' local network only\n```\n\n## Management\n\n### Automatic Deployments (GitHub Actions)\n\nOnce the GitHub runner is set up, pushes to the `main` branch automatically deploy:\n\n```bash\n# From your local machine:\ngit clone https://github.com/ipedro/moonbase.git\ncd moonbase\n# Make changes...\ngit commit -am \"Update wireguard config\"\ngit push  # 🚀 Automatically deploys to the Pi!\n```\n\n**Setup GitHub Actions runner:**\n\n1. **Create GitHub Personal Access Token:**\n   - Go to: https://github.com/settings/tokens\n   - Generate new token (classic) with `repo` scope\n   - Copy the token\n\n2. **Configure secrets:**\n   ```bash\n   # From your local machine:\n   bash scripts/setup-github-secrets.sh\n   ```\n\n3. **Verify runner:**\n   - Check: https://github.com/ipedro/moonbase/settings/actions/runners\n   - Should show \"moonbase-pi\" as active\n\n### Remote Web IDE (Code Server)\n\nAccess VS Code in your browser at `https://moonbase.yourdomain.com:8443`\n\n- Edit all config files\n- Check container logs\n- Run docker commands\n- No SSH needed\n\n**Secure it with reverse proxy** (recommended):\n- Add proxy host in Nginx Proxy Manager\n- Domain: `code.moonbase.yourdomain.com`\n- Forward to: Pi IP:8443\n- Enable SSL\n\n### Remote Management via Portainer\n\n1. **Add environment in homelab Portainer:**\n   - Settings → Environments → Add environment\n   - Agent type: Docker Standalone\n   - URL: `moonbase.yourdomain.com:9001`\n\n2. **Manage remotely:**\n   - View logs, restart services, update configs\n   - No need to SSH into the Pi\n\n### Monitoring (Optional)\n\nAdd to your homelab Prometheus config:\n\n```yaml\nscrape_configs:\n  - job_name: 'moonbase'\n    static_configs:\n      - targets: ['moonbase.yourdomain.com:9100']\n```\n\nMonitor CPU, memory, disk, network from Grafana.\n\n## Maintenance\n\n### Update all services\n\nWatchtower handles this automatically at 3 AM daily.\n\n**Manual update:**\n```bash\ncd /home/pi/moonbase\ndocker compose pull\ndocker compose up -d\n```\n\n### View logs\n\n```bash\n# All services\ndocker compose logs -f\n\n# Specific service\ndocker compose logs -f wireguard\ndocker compose logs -f cloudflare-ddns\n```\n\n### Restart services\n\n```bash\n# All services\ndocker compose restart\n\n# Specific service\ndocker compose restart wireguard\n```\n\n## Troubleshooting\n\n### WireGuard not connecting\n\n1. **Check if service is running:**\n   ```bash\n   docker compose ps\n   ```\n\n2. **Verify port forwarding:**\n   ```bash\n   # From another network:\n   nc -zvu moonbase.yourdomain.com 51820\n   ```\n\n3. **Check logs:**\n   ```bash\n   docker compose logs wireguard\n   ```\n\n### DDNS not updating\n\n1. **Check Cloudflare DDNS logs:**\n   ```bash\n   docker compose logs cloudflare-ddns\n   ```\n\n2. **Verify API token has DNS edit permissions**\n\n3. **Manually verify DNS:**\n   ```bash\n   nslookup moonbase.yourdomain.com\n   ```\n\n### No internet through VPN\n\n1. **Check IP forwarding is enabled:**\n   ```bash\n   docker exec wireguard sysctl net.ipv4.ip_forward\n   # Should return: net.ipv4.ip_forward = 1\n   ```\n\n2. **Verify AllowedIPs in client config:**\n   ```bash\n   # Should be:\n   AllowedIPs = 0.0.0.0/0\n   ```\n\n3. **Test DNS resolution:**\n   ```bash\n   # While connected to VPN:\n   nslookup google.com\n   ```\n\n## Security Notes\n\n- **WireGuard keys**: Stored in `wireguard/config/` - keep peer configs secure\n- **API tokens**: Never commit `.env` file to git (already in .gitignore)\n- **Firewall**: Pi only needs port 51820/udp open to internet\n- **Updates**: Watchtower keeps containers patched automatically\n\n## Network Architecture\n\n```\nYour Device\n    ↓\nWireGuard Client\n    ↓ (encrypted tunnel)\nInternet\n    ↓\nParents' Router (port forward 51820)\n    ↓\nMoonbase Pi (WireGuard Server)\n    ↓\nParents' ISP\n    ↓\nGeo-restricted Services (sees parents' IP)\n```\n\n## Resources\n\n- **WireGuard Documentation**: https://www.wireguard.com/\n- **Cloudflare API Docs**: https://developers.cloudflare.com/api/\n- **Portainer Docs**: https://docs.portainer.io/\n- **Homelab Repo**: https://github.com/ipedro/homelab\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipedro%2Fmoonbase","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fipedro%2Fmoonbase","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fipedro%2Fmoonbase/lists"}