Deployment notes

Deployment Notes

📚 Complete Documentation: For comprehensive deployment procedures, infrastructure details, and backup/restore operations, see the CI/CD README in the main repository.

Quick Reference

Automated Deployments

Staging deploys automatically when code is merged to main:

• GitHub Actions workflow: rebuild-staging.yaml
• No manual intervention required
• Check workflow status in GitHub Actions tab

Production requires manual trigger via GitHub Actions:

1. Navigate to Actions → "Deploy to Production"
2. Click "Run workflow"
3. Type "DEPLOY" to confirm
4. Workflow: deploy-production.yaml

Manual Deployment via Makefile

If you need to deploy manually from your local machine:

cd ci

# Deploy to staging
make deploy ENV=staging RUN=manual-$(date +%Y%m%d)

# Deploy to production
make deploy ENV=production RUN=manual-$(date +%Y%m%d)

Prerequisites:

• GCP authentication: gcloud auth login
• SSH access to the deployment VM
• Deployer SSH key configured

What Happens During Deployment

1. Code Sync: rsync transfers code to VM (excludes files, vendor, local dev folders)
2. Config Deployment: Environment-specific files copied as .new:
   • settings.php.new (both environments)
   • .htaccess.new and robots.txt.new (staging only)
3. Cleanup Script: Runs on VM with sudo to:
   • Move .new files into place
   • Run composer install
   • Rebuild Drupal cache (drush cr)
   • Set proper file permissions (www-data:www-data, 775 for files)

Common Post-Deployment Tasks

Clear Drupal cache:

ssh [email protected]
~/production-drush.sh cr   # Production
~/staging-drush.sh cr      # Staging

Run database updates:

ssh [email protected]
~/production-drush.sh updb -y   # Production
~/staging-drush.sh updb -y      # Staging

Check site status:

ssh [email protected]
~/production-drush.sh status
~/staging-drush.sh status

View logs:

ssh [email protected]
sudo tail -f /var/log/apache2/error.log

Invalidate CDN Cache

After deployment, if you need immediate cache refresh:

# Invalidate specific paths
gcloud compute url-maps invalidate-cdn-cache interledger-org \
  --path "/path/to/page" \
  --async

# Invalidate all /developers content
gcloud compute url-maps invalidate-cdn-cache interledger-org \
  --path "/developers/*" \
  --async

Backup Before Deployment

Always backup production before major changes:

cd ci
make backup ENV=production RUN=pre-deploy-$(date +%Y%m%d-%H%M%S)

See Backup and Restore documentation for more details.

Promoting Staging to Production

Common workflow for production updates:

cd ci

# 1. Backup production (safety)
make backup ENV=production RUN=pre-promotion-$(date +%Y%m%d)

# 2. Backup staging (to be promoted)
make backup ENV=staging RUN=promotion-$(date +%Y%m%d)

# 3. Restore staging to production (database + files)
make restore ENV=staging FROM-RUN=promotion-$(date +%Y%m%d) TARGETENV=production

# 4. Deploy code via GitHub Actions
# Navigate to Actions → "Deploy to Production"

Troubleshooting Deployments

Issue: Site showing old content

• Clear Drupal cache: ~/production-drush.sh cr
• Invalidate CDN cache (see above)
• Check browser cache (hard refresh: Ctrl+Shift+R)

Issue: Permission errors

ssh [email protected]
sudo chown -R www-data:www-data /var/www/production/web/sites/default/files/
sudo chmod -R 775 /var/www/production/web/sites/default/files/

Issue: White screen / 500 errors

ssh [email protected]
sudo tail -f /var/log/apache2/error.log
~/production-drush.sh status  # Check database connection

Issue: Composer errors

ssh [email protected]
cd /var/www/production
composer install --no-dev --optimize-autoloader

Testing Deployments

After deploying, verify:

# Site loads
curl -I https://interledger.org/

# Developers portal loads
curl -I https://interledger.org/developers/

# Check backend health
gcloud compute backend-services get-health drupal-sites-backend --global

# Check Drupal status
ssh [email protected]
~/production-drush.sh status

Getting Help

If you need to deploy but don't have access:

• Want a change implemented: Open a PR and ping someone in Community Slack
• ILF Tech Team: Contact the infrastructure team in the tech-team Slack channel
• Emergency: Check GitHub Actions for recent deployment status

Additional Documentation

• CI/CD README: Complete deployment documentation
• Infrastructure README: GCP architecture and operations
• Local Development: Setting up local environment
• Environments: Overview of local, staging, and production environments