HomeBase/README.md

HomeBase

Simple self-hosted Node.js Docker application with automated SSH deployment.

Features

• 🚀 Simple Express.js server
• 🐳 Docker containerized
• 🔄 Automated deployment via SSH
• ✅ Health check endpoint
• 🔐 SSH key-based authentication

Prerequisites

On your local machine:

• Node.js (for local testing)
• Docker (for local testing)
• SSH access to beepc server

On the remote server (beepc):

• Docker installed
• Docker Compose installed
• SSH access configured for user spencer

Quick Start

Local Development

# Install dependencies
npm install

# Run locally
npm start

# Visit http://localhost:3001

Deployment

Option 1: Manual Deployment (Windows)

# Run the deployment script from project root
.\scripts\deploy.bat

Option 2: Manual Deployment (Linux/Mac)

# Make script executable
chmod +x scripts/deploy.sh

# Run deployment
bash scripts/deploy.sh

Option 3: Manual Deployment (PowerShell)

# Run the deployment script from project root
.\scripts\deploy.ps1

Option 4: Automated Deployment (GitHub Actions)

1. Add your SSH private key to GitHub Secrets:

   • Go to your repository Settings > Secrets and variables > Actions
   • Add a new secret named SSH_PRIVATE_KEY
   • Paste your SSH private key content

2. Push to main branch:

   git add .
   git commit -m "Initial commit"
   git push origin main
   

3. The app will automatically deploy to spencer@beepc

SSH Setup

Ensure you have SSH key-based authentication set up:

# Generate SSH key if you don't have one
ssh-keygen -t ed25519 -C "your_email@example.com"

# Copy key to remote server
ssh-copy-id spencer@beepc

# Test connection
ssh spencer@beepc

Remote Server Setup

On beepc, ensure Docker is installed:

# Install Docker (Ubuntu/Debian)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker spencer

# Install Docker Compose
sudo apt-get update
sudo apt-get install docker-compose-plugin

# Logout and login again for group changes to take effect

API Endpoints

• GET / - Main endpoint, returns app status
• GET /health - Health check endpoint

Project Structure

HomeBase/
├── scripts/
│   ├── deploy.ps1           # PowerShell deployment script
│   ├── deploy.sh            # Bash deployment script
│   └── deploy.bat           # Windows batch deployment script
├── .github/
│   └── workflows/
│       └── deploy.yml       # GitHub Actions workflow
├── .dockerignore            # Docker ignore file
├── .gitignore              # Git ignore file
├── Dockerfile              # Docker configuration
├── docker-compose.yml      # Docker Compose configuration
├── homebase.service        # Systemd service file
├── package.json            # Node.js dependencies
├── server.js               # Express server
└── README.md               # This file

Deployment Process

The deployment script does the following:

1. Creates remote directory if it doesn't exist
2. Syncs files to remote server via rsync/scp
3. Stops existing Docker container
4. Builds new Docker image
5. Starts new container
6. Verifies container is running

Troubleshooting

Check logs on remote server

ssh spencer@beepc
cd /home/spencer/homebase
docker compose logs -f

Check container status

ssh spencer@beepc "docker ps"

Restart container

ssh spencer@beepc "cd /home/spencer/homebase && docker compose restart"

Remove and rebuild

ssh spencer@beepc "cd /home/spencer/homebase && docker compose down && docker compose up -d --build"

Accessing the App

Once deployed, access the app at:

• http://homebase.sketchferret.com (reverse proxied, no port needed)
• http://beepc:3001 (direct access from local network)
• http://localhost:3001 (direct access on the server)

Note: The app runs on port 3001 internally but is accessed via reverse proxy at the standard HTTP port.

Auto-Start on Boot

The deployment script automatically sets up a systemd service that:

• Starts the Docker container on server boot
• Restarts the container if it crashes
• Runs as the spencer user

To manually manage the service:

# Check status
ssh spencer@beepc "sudo systemctl status homebase"

# Stop service
ssh spencer@beepc "sudo systemctl stop homebase"

# Start service
ssh spencer@beepc "sudo systemctl start homebase"

# Restart service
ssh spencer@beepc "sudo systemctl restart homebase"

# Disable auto-start
ssh spencer@beepc "sudo systemctl disable homebase"

Environment Variables

You can customize settings by modifying docker-compose.yml:

environment:
  - PORT=3001  # Internal port (reverse proxy maps to standard HTTP)
  - DOMAIN=homebase.sketchferret.com  # Your domain
ports:
  - "3001:3001"  # Port mapping for reverse proxy backend

Security Notes

• Uses SSH key authentication (no passwords)
• Container runs as non-root user
• Only production dependencies installed in Docker image
• Health check endpoint for monitoring

License

MIT