Skip to main content

API Deployment Process

This guide provides step-by-step instructions for deploying API services to staging and production environments, as well as setting up new modules or services.

Prerequisites​

Before starting the deployment process, ensure you have:

  • Access to the repository and GitHub Actions
  • Appropriate permissions for the target environment
  • SSH access to the API server (for new module/service setup)
  • Understanding of the service versioning scheme

Deploy to Staging​

Follow these steps to deploy API services to the staging environment:

  1. Create Pull Request

    • Open a Pull Request from your feat/xxx branch to the develop branch
    • Ensure all code changes are reviewed and tested

  2. Review and Merge

    • Review the Pull Request with your team
    • Address any review comments
    • Merge the PR into the develop branch

  3. Navigate to GitHub Actions

    • Go to the repository on GitHub
    • Navigate to Actions > Dev Pipeline for Manual Deployment
    • Select the service you want to deploy

  4. Deploy Service

    • Click the Run workflow button
    • Select the service and version from the dropdown menus
    • Click Run workflow again to initiate the deployment

  5. Verify Deployment

    • Monitor the deployment workflow for completion
    • Verify the service is running correctly in the staging environment
New Module/Service

If you are deploying a new module or service, proceed to the New Module/Service Setup section after completing the deployment.

Deploy to Production​

Production deployments follow a more rigorous process to ensure stability and reliability.

Step 1: Create Release Branch​

Create a release or hotfix branch from the develop branch:

  • Release branch: release/x.y.z (e.g., release/1.0.0)
  • Hotfix branch: hotfix/x.y.z (e.g., hotfix/1.0.1)
Version Numbering

Follow semantic versioning (SemVer):

  • Major (x): Breaking changes
  • Minor (y): New features, backward compatible
  • Patch (z): Bug fixes, backward compatible

Step 2: Set Up Release Version​

  • Update version numbers in the appropriate configuration files
  • Ensure all version references are consistent across the codebase

Step 3: Create Pull Request to Main​

  1. Open a Pull Request from your release/x.y.z or hotfix/x.y.z branch to the main branch
  2. Wait for team approval
  3. Merge the PR after receiving all required approvals

Step 4: Sync Hotfix to Develop (Hotfix Only)​

Important for Hotfixes

If you created a hotfix/x.y.z branch, you must sync the changes back to develop:

  1. Open a Pull Request from the main branch to the develop branch
  2. This ensures the hotfix is included in future releases
  3. Review and merge the sync PR

Step 5: Verify Production Deployment​

  • Monitor the production deployment pipeline
  • Verify the service is running correctly
  • Check application logs and metrics
New Module/Service

If you are deploying a new module or service, proceed to the New Module/Service Setup section after completing the deployment.

For New Module/Service Setup​

When deploying a new API module or service for the first time, you need to configure nginx to route traffic to the new service.

Prerequisites​

  • SSH access to the API server
  • Docker and Docker Compose installed on the server
  • Understanding of the service's internal port configuration

Configuration Steps​

  1. Connect to API Server

    ssh user@api-server

  2. Stop Nginx Container

    cd nginx
    docker compose down

  3. Edit Nginx Configuration

    Open the nginx.conf file and add the following configuration:

    # Define upstream server for the new service
    upstream <path_name> {
      server <container_name>:<internal_container_port>;
    }

    # ... existing server configuration ...

    server {
      listen 443 ssl;
      # ... existing server settings ...

      # Location block for the new service
      location /<path>/ {
        resolver 127.0.0.11 valid=30s;
        rewrite ^/<path_name>/(.*)$ /$1 break;
        proxy_pass http://<path_name>;
        proxy_set_header Host $host;
        proxy_http_version 1.1;

        # WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_cache_bypass $http_upgrade;

        # Forward original headers
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        # Cookie forwarding
        proxy_pass_header Set-Cookie;
        proxy_set_header Cookie $http_cookie;

        # Timeout settings
        proxy_read_timeout 300s;
        proxy_connect_timeout 300s;
        proxy_send_timeout 300s;
        send_timeout 300s;
      }
    }
    Configuration Variables

    Replace the following placeholders:

    • <path_name>: The upstream name (e.g., api-service)
    • <container_name>: Docker container name (e.g., api-service-container)
    • <internal_container_port>: Internal port the service listens on (e.g., 8080)
    • <path>: URL path prefix for the service (e.g., api/v1)

  4. Start Nginx Container

    docker compose up -d

  5. Verify Configuration

    # Check container status
    docker ps

    # Verify nginx configuration is valid
    docker exec nginx-container nginx -t

    # Check nginx logs
    docker logs nginx-container

  6. Test the Service

    • Test the new service endpoint to ensure routing works correctly
    • Verify SSL/TLS is properly configured
    • Check that WebSocket connections work (if applicable)

Troubleshooting​

Common Issues​

Deployment fails in GitHub Actions

  • Check workflow logs for specific error messages
  • Verify service version exists in the registry
  • Ensure all required secrets and environment variables are configured

Nginx configuration errors

  • Run docker exec nginx-container nginx -t to validate configuration
  • Check nginx logs: docker logs nginx-container
  • Verify container names and ports are correct

Service not accessible after deployment

  • Verify the service container is running: docker ps
  • Check service logs: docker logs <container-name>
  • Verify nginx routing configuration matches the service path
  • Ensure firewall rules allow traffic on the configured ports