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

Basic setup for a local demo

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.

This is not an optimal setup for a production environment. See Nginx proxy and production setup guides for a production deploy.

Configurations

Some of the configuration lines in the provided docker-compose file are written in a single line for brevity and simpler 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
VERSION=2020.9

########################################################################################################################
# Ports where these services will be accessible
# In case of an "address already in use" change these ports to a higher number

# Web applications
# http://localhost:18080
LOCAL_DEMO_SPA_PORT=18080

# API Server
# http://localhost:18081
LOCAL_DEMO_API_PORT=18081

# Corredor gRPC server, nothing to see here,
# just for internal traffic between API server and corredor
LOCAL_DEMO_CRD_PORT=18082


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

services:
  webapp:
    image: cortezaproject/corteza-webapp:${VERSION}
    restart: on-failure
    depends_on: [ server ]
    # Binds internal port 80 to port LOCAL_DEMO_SPA_PORT on localhost
    ports: [ "127.0.0.1:${LOCAL_DEMO_SPA_PORT}:80" ]
    environment:
      # Monolith API settings informs webapp autoconfiguration script that we're running
      # a monolith API server.
      MONOLITH_API: "true"
      # Configure web application with API location
      API_BASEURL:  "127.0.0.1:${LOCAL_DEMO_API_PORT}"

  server:
    image: cortezaproject/corteza-server-monolith:${VERSION}
    restart: on-failure
    depends_on: [ db, corredor ]
    # Binds internal port 80 to port LOCAL_DEMO_API_PORT on localhost
    ports: [ "127.0.0.1:${LOCAL_DEMO_API_PORT}:80" ]
    env_file: [ .env ]
    environment:
      # Using name of the service, will connect to server API over internal docker network
      CORREDOR_ADDR: "corredor:80"

  corredor:
    image: cortezaproject/corteza-server-corredor:${VERSION}
    restart: on-failure
    # Binds internal port 80 to port LOCAL_DEMO_CRD_PORT on localhost
    ports: [ "127.0.0.1:${LOCAL_DEMO_CRD_PORT}:80" ]
    env_file: [ .env ]
    environment:
      # We need to replace the default CORREDOR_EXEC_CSERVERS_API_BASEURL_TEMPLATE so that
      # we can connect to it on a local network.
      #
      # Using name of the service, will connect to server API over internal docker network
      CORREDOR_EXEC_CSERVERS_API_BASEURL_TEMPLATE: "http://server/{service}"

  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: "yes" # docker-compose logs db |grep "GENERATED ROOT PASSWORD"
    healthcheck: { test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"], timeout: 20s, retries: 10 }

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
-------------------------------------------------------------------------------------------------------
basic_corredor_1   /corredor/node_modules/.bi ...   Up (healthy)     127.0.0.1:18082->80/tcp
basic_db_1         /docker-entrypoint.sh mysqld     Up (healthy)     3306/tcp, 33060/tcp
basic_server_1     bin/server serve-api             Up (healthy)     127.0.0.1:18081->80/tcp
basic_webapp_1     /entrypoint.sh                   Up (healthy)     127.0.0.1:18080->80/tcp

You can see 4 services up and running. Two of them are accessible on localhost (ports 18080 and 18081).

If you changed the ports in your .env file, the ports will be different.

Finishing the setup

  1. 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),

  2. 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.