Open Coverage Documentation: Hosting

Host open coverage on-prem

Open Coverage is distributed as 2 docker containers. One for the frontend and one for the API server.

Create GitHub Application

To run Open Coverage, you will need to create your own github application.

Required permissions

TypeAccess
ChecksRead & Write
ContentsRead & Write
IssuesRead & Write
Pull RequestsRead & Write
Commit statusesRead

After your app is created, you will need to make sure to download the private key file. Open Coverage will use this to authorize requests to the GitHub API.

Dependencies

There are 3 requirements to run Open Coverage:

  • Database (PostgreSQL recommended)
  • API Server
  • Frontend

version: "2"
services:
  postgres:
    image: postgres:12
    ports:
      - 5432:5432
    expose:
      - 5432
    environment:
      POSTGRES_USER: opencoverage
      POSTGRES_PASSWORD: secret
      POSTGRES_INITDB_ARGS: --data-checksums
      POSTGRES_DB: opencoverage

  api:
    # image: opencoverage/api:latest
    build:
      context: .
    ports:
      - 8000:8000
    expose:
      - 8000
    environment:
      PUBLIC_URL: http://localhost:3000
      DSN: postgresql://opencoverage:[email protected]:5432/opencoverage?sslmode=disable
      SCM: github
      GITHUB_APP_PEM_FILE: /app/cov.pem
      GITHUB_APP_ID: "[your github app id]"
      GITHUB_DEFAULT_INSTALLATION_ID: "[your installation id]"
      ROOT_PATH: /api
      CORS: '["http://localhost:8080"]'
    volumes:
      - {PWD}/cov.pem:/app/cov.pem
    depends_on:
      - postgres
    links:
      - postgres

  frontend:
    image: opencoverage/frontend:latest
    build:
      context: app
    ports:
      - 3000:3000
    expose:
      - 3000
    environment:
      NEXT_PUBLIC_API_URL: http://localhost:8000/
    depends_on:
      - api
    links:
      - api

API Environments Variable Configuration

Name
HOSTHost to startup on. Defaults to `0.0.0.0`
ROOT_PATHPath API is exposed at. Defaults of `/`
PUBLIC_URLPublic URL of API
CORSList of domains API should be allowed on
DSNDatabase connection string
SCMOnly supported SCM value is `github` right now
GITHUB_APP_IDID of GitHub Application
GITHUB_APP_PEM_FILEPath to pem file with private key
GITHUB_DEFAULT_INSTALLATION_IDInstallation id to use if `-` given for `--token` value in codecov upload

Frontend Environments Variable Configuration

Name
NEXT_PUBLIC_API_URLURL of public API service

Serving with NGINX

Use NGINX to serve Frontend and API:


version: "2"
services:
...
  nginx:
    image: nginx:1.19.6
    restart: always
    volumes:
      - {PWD}/conf/nginx-templates:/etc/nginx/templates
    ports:
      - 80:80
    expose:
      - 80
    depends_on:
      - api
      - frontend
    links:
      - api
      - frontend
...

Where the file `conf/nginx-templates/default.conf.template` contains:


  upstream api {
    server api:8000;
  }
  server {
      listen       80;
      listen  [::]:80;
      server_name  _;
  
      client_max_body_size 100M;
      location / {
          proxy_pass http://frontend:3000;
      }
  
      location /api/ {
        proxy_pass_header Server;
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Scheme https;  // set scheme here
        proxy_set_header X-Forwarded-Proto https;  
        proxy_pass http://api/;
      }
  }

This will expose the frontend at the root of the site and the API server at `/api`.