Add CI/CD workflows for development and production deployments
Some checks failed
Deploy Development / deploy (push) Failing after 29s
Some checks failed
Deploy Development / deploy (push) Failing after 29s
- Created `deploy-dev.yml` for automated deployment to the development server on push to the `dev` branch. - Created `deploy.yml` for automated deployment to the production server on push to the `main` or `master` branches. - Added deployment instructions in `DEPLOYMENT-PORTAINER.md` for using Portainer and Traefik. - Documented Gitea Actions deployment process in `DEPLOYMENT.md`. - Configured Traefik SSL settings in `TRAEFIK-SSL-CONFIG.md` for both development and production environments. - Implemented a deployment script `deploy.sh` for manual deployments. - Added Docker Compose configurations for development (`docker-compose.portainer.dev.yml`) and production (`docker-compose.portainer.yml`) environments. - Updated main `docker-compose.yml` to support Traefik integration and environment variable configurations.
This commit is contained in:
Frank John Begornia
264
DEPLOYMENT.md
Normal file
264
DEPLOYMENT.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# Gitea Actions Deployment Guide
|
||||
|
||||
This repository uses Gitea Actions for automated deployment to your server.
|
||||
|
||||
## Workflows
|
||||
|
||||
### 1. Deploy Workflow (`.gitea/workflows/deploy.yml`)
|
||||
Automatically deploys the application when code is pushed to `main` or `master` branch.
|
||||
|
||||
**Steps:**
|
||||
1. Builds Docker image
|
||||
2. Transfers image to deployment server
|
||||
3. Stops existing container
|
||||
4. Starts new container
|
||||
5. Runs database migrations
|
||||
6. Clears and caches Laravel configuration
|
||||
|
||||
### 2. Build and Push Workflow (`.gitea/workflows/build-push.yml`)
|
||||
Builds and pushes Docker images to a registry when a version tag is created.
|
||||
|
||||
## Required Secrets
|
||||
|
||||
Configure these secrets in your Gitea repository settings:
|
||||
`Settings` → `Secrets` → `Actions`
|
||||
|
||||
### Deployment Secrets
|
||||
|
||||
| Secret Name | Description | Example |
|
||||
|------------|-------------|---------|
|
||||
| `DEPLOY_HOST` | Deployment server hostname or IP | `192.168.1.100` or `example.com` |
|
||||
| `DEPLOY_USER` | SSH username for deployment | `deploy` or `ubuntu` |
|
||||
| `DEPLOY_SSH_KEY` | Private SSH key for authentication | `-----BEGIN RSA PRIVATE KEY-----...` |
|
||||
| `DEPLOY_PORT` | SSH port (optional, defaults to 22) | `22` |
|
||||
| `DEPLOY_DIR` | Deployment directory (optional) | `/var/www/merchbay_admin` |
|
||||
|
||||
### Docker Registry Secrets (Optional)
|
||||
|
||||
Only required if using the build-push workflow or private registry:
|
||||
|
||||
| Secret Name | Description | Example |
|
||||
|------------|-------------|---------|
|
||||
| `DOCKER_REGISTRY_URL` | Docker registry URL | `registry.example.com` or `docker.io` |
|
||||
| `DOCKER_USERNAME` | Registry username | `myuser` |
|
||||
| `DOCKER_PASSWORD` | Registry password or token | `mypassword` |
|
||||
|
||||
### Database Configuration on Server
|
||||
|
||||
Create a `.env` file in your deployment directory with database credentials:
|
||||
|
||||
```bash
|
||||
# On your deployment server
|
||||
sudo mkdir -p /var/www/merchbay_admin
|
||||
sudo nano /var/www/merchbay_admin/.env
|
||||
```
|
||||
|
||||
Add your database configuration:
|
||||
|
||||
```env
|
||||
DB_HOST=your-mysql-host
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=merchbay_admin
|
||||
DB_USERNAME=your-mysql-user
|
||||
DB_PASSWORD=your-mysql-password
|
||||
APP_ENV=production
|
||||
APP_DEBUG=false
|
||||
APP_KEY=base64:YOUR_APP_KEY_HERE
|
||||
```
|
||||
|
||||
## Setup Instructions
|
||||
|
||||
### 1. Generate SSH Key for Deployment
|
||||
|
||||
On your local machine or CI server:
|
||||
|
||||
```bash
|
||||
# Generate a new SSH key pair
|
||||
ssh-keygen -t rsa -b 4096 -f ~/.ssh/deploy_key -N ""
|
||||
|
||||
# Copy the public key to your deployment server
|
||||
ssh-copy-id -i ~/.ssh/deploy_key.pub user@your-server
|
||||
|
||||
# Copy the private key content for Gitea secret
|
||||
cat ~/.ssh/deploy_key
|
||||
```
|
||||
|
||||
### 2. Configure Gitea Secrets
|
||||
|
||||
1. Go to your Gitea repository
|
||||
2. Navigate to `Settings` → `Secrets` → `Actions`
|
||||
3. Add each required secret listed above
|
||||
4. For `DEPLOY_SSH_KEY`, paste the entire private key content
|
||||
|
||||
### 3. Prepare Deployment Server
|
||||
|
||||
On your deployment server, install Docker and Docker Compose:
|
||||
|
||||
```bash
|
||||
# Install Docker
|
||||
curl -fsSL https://get.docker.com -o get-docker.sh
|
||||
sudo sh get-docker.sh
|
||||
|
||||
# Add your user to docker group
|
||||
sudo usermod -aG docker $USER
|
||||
|
||||
# Install Docker Compose
|
||||
sudo apt-get update
|
||||
sudo apt-get install docker-compose-plugin
|
||||
|
||||
# Create deployment directory
|
||||
sudo mkdir -p /var/www/merchbay_admin
|
||||
sudo chown $USER:$USER /var/www/merchbay_admin
|
||||
|
||||
# Create .env file with database credentials
|
||||
nano /var/www/merchbay_admin/.env
|
||||
```
|
||||
|
||||
### 4. Update docker-compose.yml for Production
|
||||
|
||||
Ensure your `docker-compose.yml` references the `.env` file:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
app:
|
||||
environment:
|
||||
- DB_HOST=${DB_HOST}
|
||||
- DB_PORT=${DB_PORT}
|
||||
- DB_DATABASE=${DB_DATABASE}
|
||||
- DB_USERNAME=${DB_USERNAME}
|
||||
- DB_PASSWORD=${DB_PASSWORD}
|
||||
```
|
||||
|
||||
## Triggering Deployment
|
||||
|
||||
### Automatic Deployment
|
||||
|
||||
Push to main/master branch:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Deploy updates"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### Manual Deployment
|
||||
|
||||
1. Go to your Gitea repository
|
||||
2. Click on `Actions`
|
||||
3. Select `Deploy MerchBay Admin` workflow
|
||||
4. Click `Run workflow`
|
||||
|
||||
## Monitoring Deployment
|
||||
|
||||
### View Workflow Logs
|
||||
|
||||
1. Go to `Actions` tab in your Gitea repository
|
||||
2. Click on the running/completed workflow
|
||||
3. View logs for each step
|
||||
|
||||
### Check Application Logs
|
||||
|
||||
On your deployment server:
|
||||
|
||||
```bash
|
||||
cd /var/www/merchbay_admin
|
||||
docker compose logs -f app
|
||||
```
|
||||
|
||||
### Verify Deployment
|
||||
|
||||
```bash
|
||||
# Check container status
|
||||
docker compose ps
|
||||
|
||||
# Test application
|
||||
curl http://localhost:8080
|
||||
|
||||
# Access application shell
|
||||
docker compose exec app bash
|
||||
```
|
||||
|
||||
## Rollback Procedure
|
||||
|
||||
If deployment fails, you can quickly rollback:
|
||||
|
||||
```bash
|
||||
# On deployment server
|
||||
cd /var/www/merchbay_admin
|
||||
|
||||
# Stop current container
|
||||
docker compose down
|
||||
|
||||
# Load previous image (if available)
|
||||
docker images # Find previous image ID
|
||||
docker tag <previous-image-id> merchbay_admin:latest
|
||||
|
||||
# Start with previous version
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### SSH Connection Issues
|
||||
|
||||
```bash
|
||||
# Test SSH connection from CI to server
|
||||
ssh -i ~/.ssh/deploy_key user@your-server
|
||||
|
||||
# Check SSH key permissions
|
||||
chmod 600 ~/.ssh/deploy_key
|
||||
```
|
||||
|
||||
### Docker Permission Issues
|
||||
|
||||
```bash
|
||||
# On deployment server, ensure user is in docker group
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
```
|
||||
|
||||
### Migration Failures
|
||||
|
||||
```bash
|
||||
# Manually run migrations
|
||||
docker compose exec app php artisan migrate --force
|
||||
|
||||
# Check database connection
|
||||
docker compose exec app php artisan tinker
|
||||
>>> DB::connection()->getPdo();
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Use SSH keys, not passwords** for server authentication
|
||||
2. **Restrict SSH key** to only deployment commands if possible
|
||||
3. **Use secrets** for all sensitive data, never commit to repository
|
||||
4. **Set proper file permissions** on deployment server (755 for directories, 644 for files)
|
||||
5. **Enable firewall** on deployment server and restrict access
|
||||
6. **Use HTTPS** with SSL certificates in production
|
||||
7. **Regular backups** of database and uploaded files
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Using Docker Registry
|
||||
|
||||
To use a private registry:
|
||||
|
||||
1. Add registry secrets to Gitea
|
||||
2. Update deployment script to pull from registry instead of transferring image
|
||||
3. Use the build-push workflow to automate image publishing
|
||||
|
||||
### Zero-Downtime Deployment
|
||||
|
||||
For zero-downtime deployments, consider:
|
||||
|
||||
1. Using a load balancer
|
||||
2. Running multiple container instances
|
||||
3. Implementing blue-green deployment strategy
|
||||
|
||||
### Environment-Specific Deployments
|
||||
|
||||
Create separate workflows for staging and production:
|
||||
|
||||
- `.gitea/workflows/deploy-staging.yml` (triggered on `develop` branch)
|
||||
- `.gitea/workflows/deploy-production.yml` (triggered on `main` branch)
|
||||
Reference in New Issue
Block a user