237 lines
5.2 KiB
Markdown
237 lines
5.2 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Run locally
|
|
npm start
|
|
|
|
# Visit http://localhost:3001
|
|
```
|
|
|
|
### Deployment
|
|
|
|
### Option 1: Manual Deployment (Windows)
|
|
|
|
```bash
|
|
# Run the deployment script from project root
|
|
.\scripts\deploy.bat
|
|
```
|
|
|
|
### Option 2: Manual Deployment (Linux/Mac)
|
|
|
|
```bash
|
|
# Make script executable
|
|
chmod +x scripts/deploy.sh
|
|
|
|
# Run deployment
|
|
bash scripts/deploy.sh
|
|
```
|
|
|
|
### Option 3: Manual Deployment (PowerShell)
|
|
|
|
```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:
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
ssh spencer@beepc
|
|
cd /home/spencer/homebase
|
|
docker compose logs -f
|
|
```
|
|
|
|
### Check container status
|
|
|
|
```bash
|
|
ssh spencer@beepc "docker ps"
|
|
```
|
|
|
|
### Restart container
|
|
|
|
```bash
|
|
ssh spencer@beepc "cd /home/spencer/homebase && docker compose restart"
|
|
```
|
|
|
|
### Remove and rebuild
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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](docker-compose.yml):
|
|
|
|
```yaml
|
|
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
|