You are reading the documentation for an outdated Corteza release. 2023.9 is the latest stable Corteza release.

Production setup with MySQL database

The section covers configuration files suitable for production environment. Services are separated into two networks (internal and proxy) so that database and automation server can not be accessed from the public network.

In example volumes are mounted on server and db services to ensure that files can be accessed from the host machine (if needed).

This setup depends on you running the NginX proxy service. We recommend that you set it up beforehand.

If you prefer and use a different method to forward HTTP traffic to your Docker containers

DNS

This demo uses a dedicated domain: 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 configuration file
# (more info: https://docs.docker.com/compose/environment-variables)

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

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

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

########################################################################################################################
# Server settings

# Serve Corteza webapps alongside API
HTTP_WEBAPP_ENABLED=true

# Send actionlog to container logs as well
# ACTIONLOG_DEBUG=true

# Uncomment for extra debug info if something goes wrong
# LOG_LEVEL=debug

# Use nicer and colorful log instead of JSON
# LOG_DEBUG=true

########################################################################################################################
# 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

# 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>'
docker-compose.yaml
version: '3.5'

services:
  server:
    image: cortezaproject/corteza-server:${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 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}

  corredor:
    image: cortezaproject/corteza-server-corredor:${VERSION}
    networks: [ internal ]
    restart: on-failure
    env_file: [ .env ]

  db:
    # MySQL Database
    # See https://hub.docker.com/r/percona/percona-server for details
    image: percona:8.0
    restart: on-failure
    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.

If needed, uncomment and make changes to variables in your .env file:

  • DOMAIN

  • AUTH_JWT_SECRET

  • SMTP_*

If you uncommented local fs for data persinstance in the db and server containers, you need to prepare the directories.

Create directories and change ownership so that containers can write to it:
mkdir -p data/db data/server
chown 1001:1001 data/db
chown 4242:4242 data/server

Run the services

docker-compose up -d

Run this command in the same directory as your docker-compose.yaml file. It will start all 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
----------------------------------------------------------------------------------------------------
my_production_demo_corredor_1   docker-entrypoint.sh node  ...   Up (healthy)   80/tcp
my_production_demo_db_1         /docker-entrypoint.sh mysqld     Up (healthy)   3306/tcp, 33060/tcp
my_production_demo_server_1     /bin/corteza-server serve-api    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.

Testing the deployment

  1. Direct your browser to http://your-demo.example.tld. On your first visit, Corteza redirects you to the authentication page (/auth),

  2. create your account through the sign-up form.

  3. check the server version http://your-demo.example.tld/version

  4. check the server’s health http://your-demo.example.tld/healthcheck

  5. check the API documentation http://your-demo.example.tld/api/docs/

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.

Troubleshooting

Ports are not available

In case something else on your machine is using ports configured ports you will see error like this:

Cannot start service server: Ports are not available: listen tcp 127.0.0.1:18080: bind: address already in use

You can safely change the port to any number between 1024 and 65535. You can also replace value for services.server.ports in docker-compose.yaml to [ "80" ] and docker will pick an available port for you.

Connection to Corredor

You might see one or more connection refused errors in server container logs (docker-compose logs -f server):

{"level":"error","ts":1608125024.4714684,"logger":"corredor","caller":"corredor/service.go:427","msg":"could not load corredor server scripts","error":"rpc error: code = DeadlineExceeded desc = latest balancer error: connection error: desc = \"transport: Error while dialing dial tcp 172.23.0.2:80: connect: connection refused\"","stacktrace":"github.com/cortezaproject/corteza-server/pkg/corredor.(*service).loadServerScripts\n\t/drone/src/pkg/corredor/service.go:427"}----

If there are a couple of errors when server is starting up that’s ok. Sometimes it takes more time to start up Corredor server and Corteza server can not yet connect to it.

If problem persists, and you can see Corredor state as healthy please verify changes you might have made to the configuration.

Network proxy declared as external

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

Make sure your nginx-proxy service is up and running before running Corteza.

Further troubleshooting

If you’re continuing to have issues with Corteza, we encourage you to make contact with other users on our community server. You’ll more than likely find someone who can help you out. You can also open an issue on our cortezaproject/corteza-server GitHub repository.