Production-Ready CI/CD with Docker on GitLab – Practical Guide

7 min readUpdated on

This is the .gitlab-ci.yml I run for a Laravel app on GitLab: tests, three Docker images built with buildx, and a deploy over SSH.

1. Introduction

The pipeline tests the app, builds a Node, a PHP and an Nginx image, pushes them to the GitLab registry and deploys to one production server. Tests also run on merge requests; builds and deploy run only on main.

2. Pipeline Structure

Full Example: .gitlab-ci.yml

The complete file:

yaml
image: docker:latest

stages:
  - test
  - build
  - deploy
    
variables:
  DOCKER_BUILDKIT: 1
  DOCKER_HOST: tcp://docker:2375/
  DOCKER_TLS_CERTDIR: ""
  IMAGE_NAMESPACE: dommmin/laravel-production
  REGISTRY: registry.gitlab.com

services:
  - docker:dind

before_script:
  - docker info
  - echo "$CI_REGISTRY_PASSWORD" | docker login -u "$CI_REGISTRY_USER" --password-stdin "$CI_REGISTRY"

test_php:
  stage: test
  image: dommin/php-8.4-fpm:latest
  needs: [test_node]
  before_script:
    - git config --global --add safe.directory $(pwd)
    - composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
  script:
    - cp .env.testing .env
    - php artisan key:generate
    - php artisan ziggy:generate
    - composer larastan
    - composer pint
    - php artisan test --env=testing
  variables:
    DB_CONNECTION: sqlite
    DB_DATABASE: ":memory:"
    SESSION_DRIVER: array
  artifacts:
    paths:
      - storage/logs/
    expire_in: 1 week
  only:
    - main
    - merge_requests

test_node:
  stage: test
  image: dommin/php-8.4-fpm:latest
  before_script:
    - git config --global --add safe.directory $(pwd)
    - npm ci
    - npm run build
  script:
    - npm run format
    - npm run types
    - npm run lint
  artifacts:
    paths:
      - node_modules/
      - public/build/
    expire_in: 1 hour
  only:
    - main
    - merge_requests

build_node:
  stage: build
  image: docker:24.0.5
  needs: [test_node]
  script:
    - docker buildx create --use
    - |
      docker buildx build \
        --platform linux/amd64 \
        --file docker/node/Dockerfile \
        --tag $REGISTRY/$IMAGE_NAMESPACE/node:latest \
        --tag $REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
        --push \
        .
  only:
    - main

build_php:
  stage: build
  image: docker:24.0.5
  needs: [test_php, build_node]
  script:
    - docker buildx create --use
    - |
      docker buildx build \
        --platform linux/amd64 \
        --file docker/php/Dockerfile \
        --tag $REGISTRY/$IMAGE_NAMESPACE/php:latest \
        --tag $REGISTRY/$IMAGE_NAMESPACE/php:$CI_COMMIT_SHA \
        --push \
        --build-context node=docker-image://$REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
        .
  only:
    - main

build_nginx:
  stage: build
  image: docker:24.0.5
  needs: [test_node, build_node]
  script:
    - docker buildx create --use
    - |
      docker buildx build \
        --platform linux/amd64 \
        --file docker/nginx/Dockerfile \
        --tag $REGISTRY/$IMAGE_NAMESPACE/nginx:latest \
        --tag $REGISTRY/$IMAGE_NAMESPACE/nginx:$CI_COMMIT_SHA \
        --push \
        --build-context node=docker-image://$REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
        --build-arg HTPASSWD_USER="$HTPASSWD_USER" \
        --build-arg HTPASSWD_PASS="$HTPASSWD_PASS" \
        .
  only:
    - main

deploy_production:
  stage: deploy
  image: alpine:3.19
  needs: [build_node, build_php, build_nginx]
  before_script:
    - apk add --no-cache openssh-client
    - mkdir -p ~/.ssh
    - echo "$SSH_KEY" | tr -d '\r' > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -p $SSH_PORT $SSH_HOST >> ~/.ssh/known_hosts
  script:
    - cat "$ENV_FILE" > .env
    - echo >> .env
    - |
      echo "REGISTRY=$REGISTRY" >> .env
      echo "IMAGE_NAMESPACE=$IMAGE_NAMESPACE" >> .env
      echo "NODE_IMAGE_NAME=$IMAGE_NAMESPACE/node" >> .env
      echo "PHP_IMAGE_NAME=$IMAGE_NAMESPACE/php" >> .env
      echo "NGINX_IMAGE_NAME=$IMAGE_NAMESPACE/nginx" >> .env
      echo "TAG=$CI_COMMIT_SHA" >> .env
    - scp -P $SSH_PORT docker-compose.production.yml $SSH_USER@$SSH_HOST:~/laravel/docker-compose.yml
    - scp -P $SSH_PORT .env deploy.sh $SSH_USER@$SSH_HOST:~/laravel/
    - echo "$CI_REGISTRY_PASSWORD" | ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY"
    - ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "cd ~/laravel && chmod +x deploy.sh && ./deploy.sh"
  only:
    - main

3. Testing: PHP and Node

PHP Tests

The PHP job on its own:

yaml
test_php:
  stage: test
  image: dommin/php-8.4-fpm:latest
  needs: [test_node]
  before_script:
    - composer install --no-progress --no-interaction --prefer-dist --optimize-autoloader
  script:
    - cp .env.testing .env
    - php artisan key:generate
    - php artisan ziggy:generate
    - composer larastan
    - composer pint
    - php artisan test --env=testing
  variables:
    DB_CONNECTION: sqlite
    DB_DATABASE: ":memory:"
    SESSION_DRIVER: array

The job uses in-memory SQLite for speed and runs Larastan and Pint before the tests, so a static-analysis or style failure stops the pipeline. test_php waits for test_node (needs).

Node Tests

yaml
test_node:
  stage: test
  image: dommin/php-8.4-fpm:latest
  before_script:
    - npm ci
    - npm run build
  script:
    - npm run format
    - npm run types
    - npm run lint

npm run format, npm run types and npm run lint check formatting, types and lint rules. The frontend is built first with npm run build, and node_modules/ and public/build/ are kept as artifacts for one hour.

4. Building Docker Images

Node, PHP and Nginx are built as separate images with docker buildx:

yaml
build_node:
  stage: build
  image: docker:24.0.5
  needs: [test_node]
  script:
    - docker buildx create --use
    - |
      docker buildx build \
        --platform linux/amd64 \
        --file docker/node/Dockerfile \
        --tag $REGISTRY/$IMAGE_NAMESPACE/node:latest \
        --tag $REGISTRY/$IMAGE_NAMESPACE/node:$CI_COMMIT_SHA \
        --push \
        .

Images go to the GitLab registry, each tagged :latest and with the commit SHA. The production .env is deliberately not copied into the build context: anything baked into an image can be read by everyone who can pull it, so if Vite needs VITE_* values pass only those as build arguments. build_php and build_nginx work the same way, but take the Node image as an extra build context (--build-context node=docker-image://...), which is how the frontend build gets into them.

5. Automated Production Deployment

Deployment is SSH plus a bash script:

yaml
deploy_production:
  stage: deploy
  image: alpine:3.19
  needs: [build_node, build_php, build_nginx]
  before_script:
    - apk add --no-cache openssh-client
    - mkdir -p ~/.ssh
    - echo "$SSH_KEY" | tr -d '\r' > ~/.ssh/id_rsa
    - chmod 600 ~/.ssh/id_rsa
    - ssh-keyscan -p $SSH_PORT $SSH_HOST >> ~/.ssh/known_hosts
  script:
    - scp -P $SSH_PORT docker-compose.production.yml $SSH_USER@$SSH_HOST:~/laravel/docker-compose.yml
    - scp -P $SSH_PORT .env deploy.sh $SSH_USER@$SSH_HOST:~/laravel/
    - echo "$CI_REGISTRY_PASSWORD" | ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "docker login -u $CI_REGISTRY_USER --password-stdin $CI_REGISTRY"
    - ssh -p $SSH_PORT $SSH_USER@$SSH_HOST "cd ~/laravel && chmod +x deploy.sh && ./deploy.sh"

The SSH key comes from a CI/CD variable. The job copies docker-compose.production.yml (as docker-compose.yml), .env and deploy.sh to ~/laravel/ and runs the script. In the full file the job first builds .env from $ENV_FILE and appends the registry and image names, with TAG=$CI_COMMIT_SHA. It then logs the server in to the registry over SSH, piping the job token through stdin so it is never written to .env or to disk (CI_REGISTRY_PASSWORD is only valid while the job runs).

6. Production Checklist & Best Practices

  • ENV_FILE variable: pass the production environment as a file variable.
  • SSH keys: store them in GitLab CI/CD Variables.
  • Tests gate the build: needs ties the builds to test_php and test_node.
  • Image tags: every image is pushed as :latest and as the commit SHA, and the deploy uses the SHA. To roll back, set TAG in the server .env to an earlier SHA and run docker compose up -d.
  • Cache clearing: run php artisan config:clear after deployment.

7. Common Issues & Debugging

  • Docker connection error: check that docker:dind is running and DOCKER_HOST is set.
  • SSH permission denied: the key needs chmod 600 and must reach the job intact (the full file strips \r with tr -d).
  • Outdated images: buildx may be using its cache. Add --no-cache if needed.
  • Network issues: the production server must accept SSH connections from the runner.

8. Conclusion

That is the whole pipeline: test, build three images, deploy over SSH. It targets a single server, and the first thing I would change is pinning docker:latest, docker:dind and the PHP job image to fixed versions.

Related articles

Maintenance and growth

Do you need cleaner deployments or maintenance?

I help teams stabilize environments, improve release flow, and keep existing systems moving without unnecessary disruption.

Comments (0)
Sign in to leave a comment

You need to be signed in to add a comment.

Login

Need someone to take responsibility for the next step?

Let’s talk about your project and define a scope that actually makes sense for your goals.