Overview
The Biblioteca Virtual Frontend uses GitHub Actions to automate the build and deployment process. The CI/CD pipeline automatically builds Docker images and pushes them to Docker Hub whenever changes are pushed to the main branch.
GitHub Actions Workflow
The CI/CD pipeline is defined in .github/workflows/docker-frontend.yml:
name: Frontend CI/CD - Docker Hub
on:
push:
branches: ["main"]
jobs:
build-and-push:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Login to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build Docker image
run: docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:latest .
- name: Push Docker image
run: docker push ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:latest
Pipeline Stages
Trigger on Push
The workflow triggers automatically when code is pushed to the main branch.
Checkout Repository
Uses actions/checkout@v4 to clone the repository code.
Login to Docker Hub
Authenticates with Docker Hub using stored secrets.
Build Docker Image
Builds the Docker image using the multi-stage Dockerfile.
Push to Docker Hub
Pushes the built image to Docker Hub registry.
Required Secrets
Configure these secrets in your GitHub repository settings:
DOCKERHUB_USERNAME
Your Docker Hub username.
Settings Path: Repository > Settings > Secrets and variables > Actions > New repository secret
Name: DOCKERHUB_USERNAME
Value: your-dockerhub-username
DOCKERHUB_TOKEN
Docker Hub access token for authentication.
Settings Path: Repository > Settings > Secrets and variables > Actions > New repository secret
Name: DOCKERHUB_TOKEN
Value: your-dockerhub-access-token
Never commit Docker Hub credentials to your repository. Always use GitHub Secrets.
Creating a Docker Hub Access Token
Account Settings
Go to Account Settings > Security.
Generate Token
Click “New Access Token” and provide a description.
Copy Token
Copy the generated token immediately (it won’t be shown again).
Add to GitHub
Add the token as DOCKERHUB_TOKEN in GitHub repository secrets.
Workflow Customization
Add version tags to your Docker images:
- name: Build Docker image
run: |
docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:latest .
docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:${{ github.sha }} .
- name: Push Docker image
run: |
docker push ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:latest
docker push ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:${{ github.sha }}
Add Testing Step
Include tests before building:
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Run tests
run: npm test -- --watch=false --browsers=ChromeHeadless
- name: Build Docker image
run: docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:latest .
Multi-Environment Deployment
Deploy to different environments based on branches:
on:
push:
branches:
- main
- staging
jobs:
build-and-push:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set environment
id: set-env
run: |
if [ "${{ github.ref }}" == "refs/heads/main" ]; then
echo "env=production" >> $GITHUB_OUTPUT
else
echo "env=staging" >> $GITHUB_OUTPUT
fi
- name: Build Docker image
run: docker build -t ${{ secrets.DOCKERHUB_USERNAME }}/biblioteca-virtual-frontend:${{ steps.set-env.outputs.env }} .
Monitoring Pipeline Execution
View Workflow Runs
Navigate to your repository on GitHub:
Repository > Actions > Frontend CI/CD - Docker Hub
Check Build Logs
Click on a workflow run to view detailed logs for each step.
Workflow Status Badge
Add a status badge to your README:
Deployment Options
Pull and Run Latest Image
After the pipeline completes, pull the latest image:
docker pull your-username/biblioteca-virtual-frontend:latest
docker run -d -p 80:80 your-username/biblioteca-virtual-frontend:latest
Auto-Deploy with Watchtower
Use Watchtower to automatically update running containers:
version: '3.8'
services:
frontend:
image: your-username/biblioteca-virtual-frontend:latest
ports:
- "80:80"
restart: unless-stopped
watchtower:
image: containrrr/watchtower
volumes:
- /var/run/docker.sock:/var/run/docker.sock
command: --interval 300
Watchtower checks for image updates every 5 minutes (300 seconds) and automatically restarts containers with the latest version.
Advanced CI/CD Patterns
Cache Dependencies
Speed up builds by caching npm dependencies:
- name: Cache node modules
uses: actions/cache@v3
with:
path: ~/.npm
key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
restore-keys: |
${{ runner.os }}-node-
Parallel Jobs
Run tests and linting in parallel:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run tests
run: npm test
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run linter
run: npm run lint
build:
needs: [test, lint]
runs-on: ubuntu-latest
steps:
- name: Build and push
run: docker build and push...
Notifications
Send notifications on build completion:
- name: Notify on success
if: success()
uses: 8398a7/action-slack@v3
with:
status: ${{ job.status }}
webhook_url: ${{ secrets.SLACK_WEBHOOK }}
Troubleshooting
Authentication Failure
If login to Docker Hub fails:
- Verify
DOCKERHUB_USERNAME is correct
- Ensure
DOCKERHUB_TOKEN is valid and has not expired
- Check token permissions
Build Failure
Common issues:
- Out of memory: Increase runner resources
- Dependency errors: Clear cache and rebuild
- Dockerfile syntax: Validate Dockerfile locally
Push Failure
If pushing to Docker Hub fails:
- Verify repository exists on Docker Hub
- Check authentication token permissions
- Ensure image name matches Docker Hub repository
Best Practices
- Use specific action versions: Pin to specific versions (e.g.,
@v4)
- Secure secrets: Never log or expose secret values
- Tag images: Use semantic versioning for production releases
- Test locally: Validate builds locally before pushing
- Monitor workflows: Set up notifications for failures
- Cache dependencies: Speed up builds with caching
- Run tests: Always test before deploying
Manual Workflow Trigger
Enable manual workflow dispatch:
on:
push:
branches: ["main"]
workflow_dispatch: