docker

GITEA_ACTIONS_SETUP.md

@@ -0,0 +1,303 @@
+# Gitea Actions Setup for Docker Build and Publish
+
+This document explains how to set up Gitea Actions to automatically build and publish Docker images for the UptimeKuma Discord Bot project.
+
+## Overview
+
+The Gitea Actions workflows provide:
+- **Automated Docker image building** for both Discord bot and web backend
+- **Multi-platform support** (linux/amd64, linux/arm64)
+- **Security scanning** with Trivy
+- **Automated releases** with changelog generation
+- **Docker Compose testing** to ensure everything works together
+
+## Workflows
+
+### 1. Docker Build (`docker-build.yml`)
+
+**Triggers:**
+- Push to `main` or `develop` branches
+- Push of version tags (`v*`)
+- Pull requests to `main`
+
+**Features:**
+- Builds both Discord bot and web backend images
+- Multi-platform builds (AMD64, ARM64)
+- Pushes to Docker Hub on non-PR events
+- Generates Software Bill of Materials (SBOM)
+- Security vulnerability scanning
+- GitHub Actions cache for faster builds
+
+### 2. Docker Compose Test (`docker-compose-test.yml`)
+
+**Triggers:**
+- Push to `main` or `develop` branches
+- Pull requests to `main`
+
+**Features:**
+- Tests the complete Docker Compose setup
+- Validates Dockerfile syntax with hadolint
+- Checks service health and connectivity
+- Validates environment variable configuration
+
+### 3. Release (`release.yml`)
+
+**Triggers:**
+- Push of version tags (`v*`)
+
+**Features:**
+- Creates GitHub releases automatically
+- Generates changelog from git commits
+- Updates release notes with Docker image information
+
+## Required Secrets
+
+Configure these secrets in your Gitea repository settings:
+
+### Docker Hub Secrets
+- `DOCKER_USERNAME`: Your Docker Hub username
+- `DOCKER_PASSWORD`: Your Docker Hub access token (not password)
+
+### How to Get Docker Hub Token
+1. Go to [Docker Hub](https://hub.docker.com/)
+2. Sign in to your account
+3. Go to Account Settings → Security
+4. Create a new access token
+5. Copy the token and use it as `DOCKER_PASSWORD`
+
+## Setup Instructions
+
+### 1. Enable Gitea Actions
+
+1. Go to your Gitea repository
+2. Navigate to **Settings** → **Actions**
+3. Enable **Actions** if not already enabled
+
+### 2. Configure Secrets
+
+1. Go to **Settings** → **Secrets**
+2. Add the following secrets:
+
+| Secret Name | Description | Example |
+|-------------|-------------|---------|
+| `DOCKER_USERNAME` | Docker Hub username | `myusername` |
+| `DOCKER_PASSWORD` | Docker Hub access token | `dckr_pat_...` |
+
+### 3. Test the Workflow
+
+1. Push a commit to the `main` branch
+2. Go to **Actions** tab in your repository
+3. Watch the workflow execution
+4. Check the logs for any errors
+
+## Workflow Details
+
+### Docker Build Workflow
+
+```yaml
+# Key features:
+- Multi-platform builds (linux/amd64, linux/arm64)
+- Automatic tagging based on git refs
+- Build cache for faster subsequent builds
+- Security scanning with Trivy
+- SBOM generation for supply chain security
+```
+
+**Image Tags Generated:**
+- `latest` (for main branch)
+- `main` (branch name)
+- `v1.0.0` (version tags)
+- `1.0` (major.minor)
+- `1` (major)
+
+### Docker Compose Test Workflow
+
+```yaml
+# Key features:
+- Validates Docker Compose configuration
+- Tests service startup and health checks
+- Lints Dockerfiles with hadolint
+- Validates environment variable usage
+```
+
+### Release Workflow
+
+```yaml
+# Key features:
+- Automatic release creation on version tags
+- Changelog generation from git commits
+- Release notes with Docker image information
+- Quick start instructions included
+```
+
+## Usage Examples
+
+### Creating a Release
+
+1. **Create and push a version tag:**
+   ```bash
+   git tag v1.0.0
+   git push origin v1.0.0
+   ```
+
+2. **The workflow will:**
+   - Build Docker images with version tags
+   - Create a GitHub release
+   - Generate changelog
+   - Publish images to Docker Hub
+
+### Testing Changes
+
+1. **Create a pull request:**
+   ```bash
+   git checkout -b feature/new-feature
+   git commit -m "Add new feature"
+   git push origin feature/new-feature
+   ```
+
+2. **The workflow will:**
+   - Build images (but not push)
+   - Run security scans
+   - Test Docker Compose setup
+   - Validate configuration
+
+## Monitoring and Troubleshooting
+
+### Viewing Workflow Runs
+
+1. Go to **Actions** tab in your repository
+2. Click on a workflow run to see details
+3. Expand job steps to view logs
+
+### Common Issues
+
+#### 1. Docker Hub Authentication Failed
+```
+Error: Cannot perform an interactive login from a non TTY device
+```
+**Solution:** Check that `DOCKER_USERNAME` and `DOCKER_PASSWORD` secrets are correctly set.
+
+#### 2. Build Cache Issues
+```
+Error: failed to solve: failed to compute cache key
+```
+**Solution:** The workflow will automatically retry without cache on failure.
+
+#### 3. Security Scan Failures
+```
+Error: Trivy found vulnerabilities
+```
+**Solution:** Review the security scan results and update base images if needed.
+
+### Workflow Status Badge
+
+Add this to your README.md to show workflow status:
+
+```markdown
+[![Docker Build](https://gitea.example.com/api/badges/username/repo/status.svg)](https://gitea.example.com/username/repo/actions)
+```
+
+## Advanced Configuration
+
+### Custom Registry
+
+To use a different registry than Docker Hub:
+
+1. **Update environment variables in workflows:**
+   ```yaml
+   env:
+     REGISTRY: your-registry.com
+   ```
+
+2. **Update image names:**
+   ```yaml
+   env:
+     IMAGE_NAME_DISCORD_BOT: your-org/uptime-kuma-discord-bot
+     IMAGE_NAME_WEB_BACKEND: your-org/uptime-kuma-web-backend
+   ```
+
+### Build Arguments
+
+To pass build arguments to Docker builds:
+
+```yaml
+- name: Build and push Discord Bot image
+  uses: docker/build-push-action@v5
+  with:
+    context: ./Bot
+    file: ./Bot/Dockerfile
+    build-args: |
+      NODE_VERSION=18
+      BUILD_DATE=${{ github.event.head_commit.timestamp }}
+```
+
+### Matrix Builds
+
+To build for multiple Node.js versions:
+
+```yaml
+strategy:
+  matrix:
+    node-version: [16, 18, 20]
+```
+
+## Security Considerations
+
+### Secrets Management
+- Never commit secrets to the repository
+- Use Gitea's built-in secrets management
+- Rotate Docker Hub tokens regularly
+- Use least-privilege access tokens
+
+### Image Security
+- Base images are automatically scanned for vulnerabilities
+- SBOMs are generated for supply chain transparency
+- Multi-platform builds ensure compatibility
+- Non-root users in containers for security
+
+### Workflow Security
+- Workflows run in isolated environments
+- Secrets are encrypted and only available during execution
+- No secrets are logged or exposed in outputs
+
+## Best Practices
+
+### 1. Version Tagging
+- Use semantic versioning (`v1.0.0`)
+- Tag releases consistently
+- Include meaningful commit messages
+
+### 2. Branch Strategy
+- Use `main` for production releases
+- Use `develop` for integration testing
+- Use feature branches for new development
+
+### 3. Monitoring
+- Monitor workflow execution regularly
+- Set up notifications for failures
+- Review security scan results
+
+### 4. Maintenance
+- Keep base images updated
+- Review and update workflow dependencies
+- Monitor for deprecated actions
+
+## Support
+
+For issues with Gitea Actions:
+
+1. Check the workflow logs first
+2. Verify secrets are correctly configured
+3. Ensure Gitea Actions is enabled
+4. Check Gitea version compatibility
+5. Review this documentation
+
+## Contributing
+
+When contributing to the workflows:
+
+1. Test changes in a fork first
+2. Update documentation as needed
+3. Follow the existing workflow patterns
+4. Ensure backward compatibility
+5. Add appropriate error handling