Local Corteza demo setup with MySQL database and automation server

The section covers configuration files that are only suitable for a demo on a local environment. All services are on the same network, ports are bound to the host’s network, etc. We’re using a minimum setup with corredor automation server, and MySQL database with persistent storage.

Restarting server gives you a fresh database, and you’ll lose all your records, users and uploaded files.

This is not an optimal setup for a production environment.

Configurations

docker-compose.yaml

version: '3.5'

services:
  server:
    image: cortezaproject/corteza-server:${VERSION}
    restart: on-failure
    env_file: [ .env ]
    depends_on: [ db, corredor ]
    # Direct your browser to http://localhost:18080
    ports: [ "127.0.0.1:18080:80" ]

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

.env

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

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

# Disable actionlong for local demo
ACTIONLOG_ENABLED=false
# 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

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

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

Run the services

docker-compose up -d

Run this command in the same directory as your docker-compose.yaml file. It will start all 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
-------------------------------------------------------------------------------------------------------
demo_mysql_corredor_1   /corredor/node_modules/.bi ...   Up (healthy)     80/tcp
demo_mysql_db_1         /docker-entrypoint.sh mysqld     Up (healthy)     3306/tcp, 33060/tcp
demo_mysql_server_1     bin/server serve-api             Up (healthy)     127.0.0.1:18080->80/tcp

You can see 2 services up and running. On a modern machine Corteza initializes and configures itself in under 10 seconds.

Testing the demo

Direct your browser to http://localhost:18080. If you used other ports in your configurations, use those. On your first visit, you should be redirected to the authentication page (/auth),
create your account through the sign-up form.
check the server version http://localhost:18080/version
check the server’s health http://localhost:18080/healthcheck
check the API documentation http://localhost:18080/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.

With disabled email capabilities (unconfigured SMTP_* options) all email sending is offline and with it, email confirmation on sign-up.

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.