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
2026-04-24 13:45:01 +00:00 · 2026-01-30 19:14:52 +00:00
parent 08d7ee16af
commit 97790045ff
6 changed files with 520 additions and 3 deletions
--- a/.github/workflows/create-release.yml
+++ 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
--- 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
+
--- a/QUICKSTART.md
+++ 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
--- 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`
--- a/create-caprover-releases.sh
+++ 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"
--- a/releases/README.md
+++ 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