GuidesAPIChangelogSupportStatusCodecov HomeTry Codecov for Free
Guides
These docs are for v4.6. Click to read the latest docs for v2023.

Deploying with Docker Compose

Using Codecov's official Docker image and docker-compose

Suggest Edits

🚧

Docker Compose is only meant for trialing Codecov Self-Hosted

Docker Compose is a helpful approach to initially trial an install of Codecov Self-Hosted

However, for ongoing management of enterprise-grade implementations of Codecov Self-Hosted, we only recommend using Terraform.

Installing

Please follow the directions below to install Codecov.

Prerequisites

Install and run Codecov Enterprise

# Download assets
curl -fsSL https://raw.githubusercontent.com/codecov/enterprise/v4.6/general/codecov.yml > codecov.yml
curl -fsSL https://raw.githubusercontent.com/codecov/enterprise/v4.6/general/docker-compose.yml > docker-compose.yml

# Start Codecov Enterprise
docker-compose up -d

Don't forget to configure your codecov.yml by adding a trial key and a cookie secret.

📘

Next Steps

Codecov Self-Hosted will not run without a trial license key.

Once you have setup your license key and modified the codecov.yml to add a unique cookie string, you may navigate to localhost or http://127.0.0.1/ (or your DOCKER_HOST otherwise set in /etc/hosts) to see the UI of Codecov and begin setting up Oauth with your Git provider.

❗️

Receiving following error?

ERROR: Couldn't connect to Docker daemon at http+docker://localunixsocket - is it running?

  1. service docker start
  2. Try sudo: sudo docker-compose up -d

Logs

# all logs
docker-compose logs -f
# just web logs
docker-compose logs -f web

Upgrading

To upgrade Codecov, please follow the directions below.

docker-compose pull												 # pull new version
docker-compose stop web worker             # stop old containers
docker-compose rm -f web worker            # remove old containers
docker-compose up -d --no-deps web worker  # start new containers
docker-compose restart nginx  					   # restart nginx
  • New versions are tagged here.
  • The Docker latest version will be updated with stable releases, which may slightly lag tagged releases.

Restarting

It is important to restart nginx, web, and worker when changing configuration.

docker-compose restart web worker nginx

If you change the docker-compose.yml you will need to down/up the services as demonstrated next.

docker-compose down
docker-compose up -d

Scaling Nodes

Coming soon.

Enable SSL

To enable SSL, please follow the directions below.

Add SSL server in nginx.conf.

...other nginx.conf is above...
    keepalive_timeout 65;

    # REMOVE OLD SERVER
    # server {
    #     listen          80;
    #
    #     location / {
    #         proxy_pass_header Server;
    #         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    #         proxy_set_header X-Real-IP $remote_addr;
    #         proxy_set_header X-Scheme $scheme;
    #         proxy_set_header Host $http_host;
    #         proxy_redirect off;
    #         proxy_pass http://frontends;
    #     }
    # }

    # ADD NEW SERVER FOR 80 and 443
    server {
       listen         80;
       return         301 https://$host$request_uri;
       client_max_body_size  0;  # accept all file upload sizes
    }

    server {
        listen                     443;
        keepalive_timeout          5;
        ssl                        on;
        ssl_certificate            /etc/nginx/codecov.crt;
        ssl_certificate_key        /etc/nginx/codecov.key;
        ssl_session_cache          shared:SSL:10m;
        ssl_session_timeout        10m;
        ssl_protocols              TLSv1.2;
        ssl_prefer_server_ciphers  on;
        ssl_ciphers                ECDHE-RSA-AES256-SHA384:AES256-SHA256:HIGH:!MD5:!aNULL:!eNULL:!NULL:!DH:!EDH:!AESGCM:!3DES;
        client_max_body_size  0;  # accept all file upload sizes
   
        location / {
            proxy_pass_header Server;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Scheme $scheme;
            proxy_set_header Host $http_host;
            proxy_redirect off;
            proxy_pass http://frontends;
        }
    }
}

Include certificates in docker-compose.yml.

services:
  nginx:
    volumes:
      - ./codecov.crt:/etc/nginx/codecov.crt:ro
      - ./codecov.key:/etc/nginx/codecov.key:ro

Once you have adjusted both the nginx.conf and the docker-compose.yml, restart the system via docker-compose down && docker-compose up -d.

Report archiving

Report archiving is enabled by default. Codecov will store uploaded reports in their raw, unprocessed form. This can help debug coverage, and reduce vendor lock-in.

Enabled

services:
  web:
    volumes:
      - archive-volume:/archive
  worker:
    volumes:
      - archive-volume:/archive
volumes:
  archive-volume:

Disabled

services:
  web:
    volumes:
      # - archive-volume:/archive
  worker:
    volumes:
      # - archive-volume:/archive
volumes:
  # archive-volume:

📘

The archive folder may get very large over time.

Depending on your usage, the archive folder may become very large. We recommend mounting a NFS drive that can scale with demand.

Adding SSL pem for your git provider

Do you have a self-signed certificate with your git service provider? Please follow these directions to include the cert.pem to enable ssl communication.

Provide the certificate in the volume list when starting Codecov. It is important to name the file after the service provider listed in your configuration.

services:
  web:
    volumes:
      - ./github_enterprise.pem:/config/github_enterprise.pem:ro
  worker:
    volumes:
      - ./github_enterprise.pem:/config/github_enterprise.pem:ro

❗️

Docker Single Container

Codecov does not provide support for Docker Single Container deployments

Updated over 3 years ago

What’s Next