Production setup

You can use similar steps when deploying a staging or a demo environment.

This setup depends on you running the Nginx proxy service.

Make sure your nginx-proxy service is up and running before running Corteza. In other cases, you might get an error like:

ERROR: Network proxy declared as external, but could not be found. Please create the network manually using `docker network create proxy` and try again.

If nginx-proxy refuses to start, inspect your configuration files and compare them with ones provided in the Nginx proxy section.

DNS

This demo uses 2 example domains; your-demo.example.tld and api.your-demo.example.tld.

You need to configure your DNS by adding two hosts and point them to the IP address (A record) or the hostname (CNAME record) of the server you’re using for running Corteza.

Configurations

Some of the configuration options in the docker-compose are in-lined for brevity and easier enabling/disabling (commenting-out).

Some operating systems do not like files that start with a dot, so make sure .env file is properly named.

.env

########################################################################################################################
# docker-compose supports environment variable interpolation/substitution in compose configuraiton file
# (more info: https://docs.docker.com/compose/environment-variables)

########################################################################################################################
# General settings
DOMAIN=your-demo.example.tld
VERSION=2020.9

########################################################################################################################
# Database connection

DB_DSN=dbuser:dbpass@tcp(db:3306)/dbname?collation=utf8mb4_general_ci

########################################################################################################################
# Authentication

# Secret to use for JWT token
# Make sure you change it (>30 random characters) if
# you expose your deployment to outside traffic
AUTH_JWT_SECRET=this-is-only-for-demo-purpose--make-sure-you-change-it-for-production

########################################################################################################################
# SMTP (mail sending) settings

# Disable email confirmation for sign-up protocol to allow more seamless setup without the need
# for SMTP Server
#PROVISION_SETTINGS_AUTH_INTERNAL_SIGNUP_EMAIL_CONFIRMATION_REQUIRED=false

# Point this to your local or external SMTP server
SMTP_HOST=smtp-server.example.tld:587
SMTP_USER=postmaster@smtp-server.example.tld
SMTP_PASS=this-is-your-smtp-password
SMTP_FROM='"Demo" <info@your-demo.example.tld>'


########################################################################################################################
# Corredor service settings

# Corredor address is used in Corredor service for grpc server configuration
# and inside Server for configuring corredor gRPC client with location for corredor server
# If these two values are different in your environment for
CORREDOR_ADDR=corredor:80

docker-compose.yaml

version: '3.5'

services:
  webapp:
    image: cortezaproject/corteza-webapp:${VERSION}
    restart: on-failure
    depends_on: [ server ]
    networks: [ proxy ]
    environment:
      # VIRTUAL_HOST helps NginX proxy route trafic for specific virtual host to
      # this container
      VIRTUAL_HOST:     ${DOMAIN}
      # This is needed only if you are using NginX Lets-Encrypt companion
      # (see docs.cortezaproject.org for details)
      LETSENCRYPT_HOST: ${DOMAIN}
      # Monolith API settings informs webapp autoconfiguration script that we're running
      # a monolith API server.
      MONOLITH_API: "true"

  server:
    image: cortezaproject/corteza-server-monolith:${VERSION}
    restart: on-failure
    env_file: [ .env ]
    depends_on: [ db, corredor ]
    networks: [ proxy, internal ]
    # Uncomment to use local fs for data persistence
    # volumes: [ "./data/server:/data" ]
    environment:
      # VIRTUAL_HOST helps NginX proxy route traffic for specific virtual host to
      # this container
      # This value is also picked up by initial boot auto-configuration procedure
      # If this is changed, make sure you change settings accordingly
      VIRTUAL_HOST: api.${DOMAIN}
      # This is needed only if you are using NginX Lets-Encrypt companion
      # (see docs.cortezaproject.org for details)
      LETSENCRYPT_HOST: api.${DOMAIN}

  corredor:
    image: cortezaproject/corteza-server-corredor:${VERSION}
    networks: [ internal ]
    restart: on-failure
    env_file: [ .env ]
    # In case you do not follow the usual setup with $DOMAIN and api.$DOMAIN, please see the
    # Documentation on how you can configure Corredor API endpoints with CORREDOR_EXEC_CSERVERS_API_BASEURL_TEMPLATE,
    # CORREDOR_EXEC_CSERVERS_API_HOST and other CORREDOR_EXEC_CSERVERS_* variables.

  db:
    # MySQL Database
    # See https://hub.docker.com/r/percona/percona-server for details
    image: percona:8.0
    restart: on-failure
    # Uncomment to use local fs for data persistence
    # volumes: [ "./data/db:/var/lib/mysql" ]
    environment:
      # To be picked up by percona image when creating the database
      # Must match with DB_DSN settings inside .env
      #
      # Warning: these are values that are only used on 1st start
      #          if you want to change it later, you need to do that
      #          manually inside db container
      MYSQL_DATABASE: dbname
      MYSQL_USER:     dbuser
      MYSQL_PASSWORD: dbpass
      MYSQL_RANDOM_ROOT_PASSWORD: random # docker-compose logs db |grep "GENERATED ROOT PASSWORD"
    healthcheck: { test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"], timeout: 20s, retries: 10 }
    networks: [ internal ]



networks:
  internal: {}
  proxy: { external: true }

Create an empty directory with the .env and docker-compose.yaml files. You can adjust the provided example configuration files as you see fit.

Make sure to change the AUTH_JWT_SECRET value to something else.

Run the services

docker-compose up -d

Run this command in the same directory as your docker-compose.yaml file. It will start all of the services based on the configurations provided in the configuration files.

You can check if everything is running correctly by executing the docker-compose ps command. The output should be similar to this one:

        Name                       Command                  State              Ports
-------------------------------------------------------------------------------------------
production_corredor_1   docker-entrypoint.sh node  ...   Up (healthy)   80/tcp
production_db_1         /docker-entrypoint.sh mysqld     Up             3306/tcp, 33060/tcp
production_server_1     /bin/corteza-server serve-api    Up (healthy)   80/tcp
production_webapp_1     /entrypoint.sh                   Up (healthy)   80/tcp

You can see four services up and running.

Your services should soon be available on the configured domains in a matter of minutes.

Finishing the setup

Direct your browser to http://your-demo.example.tld. On your first visit, Corteza redirects you to the authentication page (/auth),
create your account through the sign-up form.

The first user gets automatically promoted to an administrator. You can add additional users by using the sign-up form or by adding them in the administration panel.