From 97790045fff1955f18a0598da580ebb618c4dacb Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 30 Jan 2026 19:14:52 +0000 Subject: [PATCH] Add GitHub Actions for automated release builds and deployment tools - Created GitHub Actions workflow for automated release packaging - Triggers on git tags (v*) or manual workflow dispatch - Builds uncompressed .tar files for CapRover (as required) - Creates checksums and deployment instructions - Automatically publishes to GitHub Releases - Added release build script (create-caprover-releases.sh) - Generates backend-caprover-{version}.tar (uncompressed) - Generates frontend-caprover-{version}.tar (uncompressed) - Creates documentation package (compressed for convenience) - Generates SHA256 checksums for verification - Created QUICKSTART.md for rapid deployment guide - Option 1: Pre-built releases (fastest) - Option 2: Deploy from source (latest changes) - Verification steps and troubleshooting - Updated documentation for CapRover tar format - CapRover requires uncompressed .tar files (not .tar.gz) - Updated all references in README, QUICKSTART, and releases/README - Added clear notes about file format requirements - Updated .gitignore to exclude release artifacts but keep README - Updated main README with CapRover deployment section This enables automated release creation on tag push and provides easy deployment packages for CapRover users. https://claude.ai/code/session_01NfGGGQ9Zn6ue7PRZpAoB2N --- .github/workflows/create-release.yml | 194 +++++++++++++++++++++++++++ .gitignore | 6 + QUICKSTART.md | 140 +++++++++++++++++++ README.md | 33 ++++- create-caprover-releases.sh | 73 ++++++++++ releases/README.md | 77 +++++++++++ 6 files changed, 520 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/create-release.yml create mode 100644 QUICKSTART.md create mode 100755 create-caprover-releases.sh create mode 100644 releases/README.md diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml new file mode 100644 index 0000000..9e15996 --- /dev/null +++ b/.github/workflows/create-release.yml @@ -0,0 +1,194 @@ +name: Create CapRover Release Packages + +on: + push: + tags: + - 'v*' + workflow_dispatch: + inputs: + version: + description: 'Version tag (e.g., v1.0.0)' + required: false + type: string + +permissions: + contents: write + +jobs: + create-release: + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set version + id: version + run: | + if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "${{ inputs.version }}" ]; then + VERSION="${{ inputs.version }}" + elif [ "${{ github.event_name }}" = "push" ]; then + VERSION="${GITHUB_REF#refs/tags/}" + else + VERSION=$(git describe --tags --always) + fi + echo "VERSION=${VERSION}" >> $GITHUB_OUTPUT + echo "Building release version: ${VERSION}" + + - name: Create releases directory + run: mkdir -p releases + + - name: Create backend package + run: | + cd backend + tar -cf "../releases/backend-caprover-${{ steps.version.outputs.VERSION }}.tar" \ + --exclude='__pycache__' \ + --exclude='*.pyc' \ + --exclude='.env' \ + --exclude='venv' \ + --exclude='.git' \ + . + cd .. + + - name: Create frontend package + run: | + cd frontend + tar -cf "../releases/frontend-caprover-${{ steps.version.outputs.VERSION }}.tar" \ + --exclude='node_modules' \ + --exclude='.next' \ + --exclude='.env' \ + --exclude='.env.local' \ + --exclude='.git' \ + . + cd .. + + - name: Create documentation package + run: | + tar -czf "releases/documentation-${{ steps.version.outputs.VERSION }}.tar.gz" \ + CAPROVER_DEPLOYMENT.md \ + QUICKSTART.md \ + README.md \ + backend/README.md \ + frontend/README.md \ + releases/README.md || true + + - name: Generate checksums + run: | + cd releases + sha256sum backend-caprover-${{ steps.version.outputs.VERSION }}.tar frontend-caprover-${{ steps.version.outputs.VERSION }}.tar documentation-${{ steps.version.outputs.VERSION }}.tar.gz > checksums-${{ steps.version.outputs.VERSION }}.txt + cat checksums-${{ steps.version.outputs.VERSION }}.txt + cd .. + + - name: Create deployment instructions + run: | + cat > releases/DEPLOYMENT-${{ steps.version.outputs.VERSION }}.txt << 'EOF' + Docker Swarm Terminal - CapRover Deployment + Version: ${{ steps.version.outputs.VERSION }} + + Quick Deployment: + + 1. Backend: + - Create app in CapRover: terminalbackend + - Enable HTTPS + - Upload: backend-caprover-${{ steps.version.outputs.VERSION }}.tar + - Verify logs show: "✓ Docker connection verified on startup" + + 2. Frontend: + - Create app in CapRover: terminalfrontend + - Enable HTTPS + - Set env: NEXT_PUBLIC_API_URL=https://terminalbackend.yourdomain.com + - Upload: frontend-caprover-${{ steps.version.outputs.VERSION }}.tar + + 3. Test: + curl https://terminalbackend.yourdomain.com/api/health + + For detailed instructions, extract and read documentation-${{ steps.version.outputs.VERSION }}.tar.gz + + Checksums (SHA256): + $(cat releases/checksums-${{ steps.version.outputs.VERSION }}.txt) + EOF + + - name: List release files + run: | + echo "=== Release Files ===" + ls -lh releases/ + echo "" + echo "=== Checksums ===" + cat releases/checksums-${{ steps.version.outputs.VERSION }}.txt + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + if: startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' + with: + tag_name: ${{ steps.version.outputs.VERSION }} + name: Release ${{ steps.version.outputs.VERSION }} + draft: false + prerelease: false + generate_release_notes: true + body: | + ## Docker Swarm Terminal - CapRover Release ${{ steps.version.outputs.VERSION }} + + ### 📦 Deployment Packages + + Pre-built packages ready for CapRover deployment: + - `backend-caprover-${{ steps.version.outputs.VERSION }}.tar` - Backend Flask application (uncompressed tar for CapRover) + - `frontend-caprover-${{ steps.version.outputs.VERSION }}.tar` - Frontend Next.js application (uncompressed tar for CapRover) + - `documentation-${{ steps.version.outputs.VERSION }}.tar.gz` - Complete documentation + + **Note**: CapRover requires uncompressed `.tar` files. The backend and frontend packages are uncompressed for direct upload to CapRover. + + ### 🚀 Quick Deploy + + 1. **Backend**: Upload `backend-caprover-*.tar` to your CapRover backend app + 2. **Frontend**: Upload `frontend-caprover-*.tar` to your CapRover frontend app + 3. **Verify**: Check logs for "✓ Docker connection verified on startup" + + ### 📝 Documentation + + - See `QUICKSTART.md` for step-by-step deployment + - Read `CAPROVER_DEPLOYMENT.md` for detailed configuration + - Check `checksums-*.txt` for package verification + + ### 🔐 Security + + **Important**: Change default credentials after deployment! + - Default username: `admin` + - Default password: `admin123` + + Set `ADMIN_USERNAME` and `ADMIN_PASSWORD` environment variables in CapRover. + + ### ✅ Verification + + ```bash + # Verify checksums + sha256sum -c checksums-${{ steps.version.outputs.VERSION }}.txt + + # Test backend + curl https://your-backend.domain.com/api/health + ``` + + ### 🐛 Troubleshooting + + If you see "Cannot connect to Docker" error: + 1. Check backend logs for diagnostic output + 2. Ensure `captain-definition` is properly configured + 3. Verify container runs as root with Docker socket mounted + + See `CAPROVER_DEPLOYMENT.md` for detailed troubleshooting. + files: | + releases/backend-caprover-${{ steps.version.outputs.VERSION }}.tar + releases/frontend-caprover-${{ steps.version.outputs.VERSION }}.tar + releases/documentation-${{ steps.version.outputs.VERSION }}.tar.gz + releases/checksums-${{ steps.version.outputs.VERSION }}.txt + releases/DEPLOYMENT-${{ steps.version.outputs.VERSION }}.txt + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + + - name: Upload artifacts + uses: actions/upload-artifact@v4 + with: + name: caprover-release-${{ steps.version.outputs.VERSION }} + path: releases/ + retention-days: 90 diff --git a/.gitignore b/.gitignore index e0d3450..740207f 100644 --- a/.gitignore +++ b/.gitignore @@ -52,3 +52,9 @@ out/ build/ .vercel +# CapRover releases (keep README) +releases/*.tar +releases/*.tar.gz +releases/checksums-*.txt +releases/DEPLOYMENT-*.txt + diff --git a/QUICKSTART.md b/QUICKSTART.md new file mode 100644 index 0000000..a759dfb --- /dev/null +++ b/QUICKSTART.md @@ -0,0 +1,140 @@ +# Quick Start Guide + +Get up and running with Docker Swarm Terminal in minutes. + +## Prerequisites + +- CapRover server set up and running +- CapRover CLI installed: `npm install -g caprover` +- Git repository cloned locally + +## Option 1: Deploy from Pre-built Releases (Fastest) + +### Backend + +1. Download `releases/backend-caprover-{version}.tar` from [GitHub Releases](https://github.com/johndoe6345789/docker-swarm-termina/releases) +2. In CapRover dashboard: + - Create app named `terminalbackend` + - Enable HTTPS + - Go to "Deployment" tab + - Upload the `.tar` file (uncompressed - required by CapRover) +3. Wait for deployment to complete +4. Check logs for: `✓ Docker connection verified on startup` + +### Frontend + +1. Download `releases/frontend-caprover-{version}.tar` from [GitHub Releases](https://github.com/johndoe6345789/docker-swarm-termina/releases) +2. In CapRover dashboard: + - Create app named `terminalfrontend` + - Enable HTTPS + - Set environment variable: + - `NEXT_PUBLIC_API_URL=https://terminalbackend.yourdomain.com` + - Upload the `.tar` file (uncompressed - required by CapRover) +3. Visit your frontend URL + +## Option 2: Deploy from Source (Latest Changes) + +### Backend + +```bash +# Login to CapRover +caprover login + +# Navigate to backend +cd backend + +# Deploy +caprover deploy + +# Check logs +caprover logs terminalbackend --follow +``` + +### Frontend + +```bash +cd frontend +caprover deploy +``` + +## Verification + +### Backend Health Check + +```bash +curl https://terminalbackend.yourdomain.com/api/health +# Should return: {"status":"healthy"} +``` + +### Login Test + +```bash +curl -X POST https://terminalbackend.yourdomain.com/api/auth/login \ + -H "Content-Type: application/json" \ + -d '{"username":"admin","password":"admin123"}' +``` + +### Container List + +```bash +# Use the token from login response +curl https://terminalbackend.yourdomain.com/api/containers \ + -H "Authorization: Bearer {your-token}" +``` + +## Troubleshooting + +### "Cannot connect to Docker" Error + +1. Check backend logs in CapRover dashboard +2. Look for diagnostic output: + ``` + === Docker Environment Diagnosis === + ``` +3. Verify: + - Socket exists: `✓ Docker socket exists` + - Permissions: `Readable: True, Writable: True` + - User: `Current user: root` + +4. If socket not found or not writable: + - Ensure `captain-definition` has correct `serviceUpdateOverride` + - Redeploy the app (may need to delete and recreate) + +### Frontend Can't Connect to Backend + +1. Verify backend URL in frontend environment variables +2. Check CORS is enabled (it should be by default) +3. Ensure both apps have HTTPS enabled +4. Check browser console for errors + +### Container List Empty + +- Verify Docker is running on CapRover host +- Check if user has permission to see containers +- Try running: `docker ps` on the host machine + +## Security + +**Important**: Change default credentials! + +1. In CapRover dashboard, go to backend app +2. Set environment variables: + - `ADMIN_USERNAME=your_username` + - `ADMIN_PASSWORD=your_secure_password` +3. Restart the app + +## Next Steps + +- Read [CAPROVER_DEPLOYMENT.md](CAPROVER_DEPLOYMENT.md) for detailed configuration +- Review [backend/README.md](backend/README.md) for API documentation +- Check [frontend/README.md](frontend/README.md) for frontend details +- Customize the interface and add features + +## Getting Help + +If you encounter issues: + +1. Check application logs (most diagnostic info is there) +2. Review [CAPROVER_DEPLOYMENT.md](CAPROVER_DEPLOYMENT.md) troubleshooting section +3. Ensure CapRover and Docker are up to date +4. Open an issue with logs and diagnostic output diff --git a/README.md b/README.md index a35a27f..afcc053 100644 --- a/README.md +++ b/README.md @@ -27,11 +27,28 @@ A modern, secure web interface for managing Docker containers with interactive t ### Deployment - **Docker** - Containerized deployment - **Docker Compose** - Multi-container orchestration +- **CapRover** - Docker Swarm deployment platform - **GHCR** - GitHub Container Registry for images ## Quick Start -### Using Docker Compose (Recommended) +### Using CapRover (Recommended for Production) + +Pre-built deployment packages are available in [Releases](https://github.com/johndoe6345789/docker-swarm-termina/releases): + +1. Download the latest release packages: + - `backend-caprover-{version}.tar` (uncompressed - required by CapRover) + - `frontend-caprover-{version}.tar` (uncompressed - required by CapRover) + +2. Deploy to CapRover: + - Upload backend `.tar` file to your CapRover backend app + - Upload frontend `.tar` file to your CapRover frontend app + +For detailed instructions, see: +- **[QUICKSTART.md](QUICKSTART.md)** - Fast deployment guide +- **[CAPROVER_DEPLOYMENT.md](CAPROVER_DEPLOYMENT.md)** - Complete CapRover setup guide + +### Using Docker Compose (Local Development) 1. Clone the repository: ```bash @@ -129,9 +146,19 @@ The frontend will be available at http://localhost:3000 ### Health - `GET /api/health` - Health check endpoint -## Docker Images +## Deployment Options -Images are automatically built and pushed to GitHub Container Registry on every push to main: +### CapRover (Docker Swarm) + +**Production-ready deployment packages** are automatically built and published to [GitHub Releases](https://github.com/johndoe6345789/docker-swarm-termina/releases). + +- **Quick Deploy**: Upload pre-built tar files to CapRover +- **Documentation**: See [CAPROVER_DEPLOYMENT.md](CAPROVER_DEPLOYMENT.md) +- **Includes**: Enhanced Docker socket debugging and diagnostics + +### Docker Images (GHCR) + +Images are automatically built and pushed to GitHub Container Registry: - Backend: `ghcr.io/johndoe6345789/docker-swarm-termina-backend` - Frontend: `ghcr.io/johndoe6345789/docker-swarm-termina-frontend` diff --git a/create-caprover-releases.sh b/create-caprover-releases.sh new file mode 100755 index 0000000..5635e26 --- /dev/null +++ b/create-caprover-releases.sh @@ -0,0 +1,73 @@ +#!/bin/bash +# Script to create CapRover deployment tar files for releases + +set -e + +echo "Creating CapRover deployment packages..." + +# Create releases directory if it doesn't exist +mkdir -p releases + +# Get version from git or use timestamp +VERSION=$(git describe --tags --always 2>/dev/null || date +%Y%m%d-%H%M%S) + +# Backend tar file (CapRover requires uncompressed tar) +echo "Creating backend package..." +cd backend +tar -cf "../releases/backend-caprover-${VERSION}.tar" \ + --exclude='__pycache__' \ + --exclude='*.pyc' \ + --exclude='.env' \ + --exclude='venv' \ + --exclude='.git' \ + . +cd .. + +echo "✓ Created: releases/backend-caprover-${VERSION}.tar" + +# Frontend tar file (CapRover requires uncompressed tar) +echo "Creating frontend package..." +cd frontend +tar -cf "../releases/frontend-caprover-${VERSION}.tar" \ + --exclude='node_modules' \ + --exclude='.next' \ + --exclude='.env' \ + --exclude='.env.local' \ + --exclude='.git' \ + . +cd .. + +echo "✓ Created: releases/frontend-caprover-${VERSION}.tar" + +# Create a compressed documentation package (for download convenience) +echo "Creating documentation package..." +tar -czf "releases/documentation-${VERSION}.tar.gz" \ + CAPROVER_DEPLOYMENT.md \ + QUICKSTART.md \ + README.md \ + backend/README.md \ + frontend/README.md 2>/dev/null || true + +echo "✓ Created: releases/documentation-${VERSION}.tar.gz" + +# Create checksums +echo "Creating checksums..." +cd releases +sha256sum backend-caprover-${VERSION}.tar frontend-caprover-${VERSION}.tar documentation-${VERSION}.tar.gz > "checksums-${VERSION}.txt" +cd .. + +echo "✓ Created: releases/checksums-${VERSION}.txt" + +echo "" +echo "=== Release Packages Created ===" +echo "Version: ${VERSION}" +echo "" +ls -lh releases/backend-caprover-${VERSION}.tar releases/frontend-caprover-${VERSION}.tar releases/documentation-${VERSION}.tar.gz +echo "" +echo "To deploy to CapRover:" +echo " 1. Upload backend-caprover-${VERSION}.tar to your backend app" +echo " 2. Upload frontend-caprover-${VERSION}.tar to your frontend app" +echo "" +echo "Or use CapRover CLI from the respective directories:" +echo " cd backend && caprover deploy" +echo " cd frontend && caprover deploy" diff --git a/releases/README.md b/releases/README.md new file mode 100644 index 0000000..caab09c --- /dev/null +++ b/releases/README.md @@ -0,0 +1,77 @@ +# CapRover Release Packages + +This directory contains pre-built deployment packages for CapRover. + +## Files + +Each release includes: +- `backend-caprover-{version}.tar` - Backend Flask application (uncompressed for CapRover) +- `frontend-caprover-{version}.tar` - Frontend Next.js application (uncompressed for CapRover) +- `documentation-{version}.tar.gz` - Deployment documentation (compressed) +- `checksums-{version}.txt` - SHA256 checksums for verification + +**Important**: CapRover requires uncompressed `.tar` files for deployment. The backend and frontend packages are provided as uncompressed tarballs. + +## Deployment + +### Option 1: Upload via CapRover Dashboard + +1. Log into your CapRover dashboard +2. Navigate to your app +3. Click "Deploy via tarball" +4. Upload the corresponding `.tar` file (not `.tar.gz` - CapRover requires uncompressed tar) +5. Wait for deployment to complete + +### Option 2: Use CapRover CLI + +```bash +# Extract the tar file +mkdir backend-temp +tar -xf backend-caprover-{version}.tar -C backend-temp +cd backend-temp + +# Deploy using CLI +caprover deploy + +# Clean up +cd .. +rm -rf backend-temp +``` + +### Option 3: Deploy from Source + +For the latest changes, deploy directly from source: + +```bash +# Backend +cd backend +caprover deploy + +# Frontend +cd frontend +caprover deploy +``` + +## Verification + +Verify package integrity using checksums: + +```bash +sha256sum -c checksums-{version}.txt +``` + +## Build Your Own + +To build release packages from source: + +```bash +./create-caprover-releases.sh +``` + +This will create new packages in this directory. + +## See Also + +- [CAPROVER_DEPLOYMENT.md](../CAPROVER_DEPLOYMENT.md) - Complete deployment guide +- [Backend README](../backend/README.md) - Backend documentation +- [Frontend README](../frontend/README.md) - Frontend documentation