Running Corteza on a local machine

This is a guide on how to run Corteza on a local machine, describing steps needed to achieve that and how repositories are connected on the backend and frontend. More information about Corteza you can find in the official documentation.

https://github.com/cortezaproject
https://docs.cortezaproject.org/corteza-docs/2021.9/index.html

Step 1: run corteza-server from Docker

1. Repository corteza-server is the main backend repository. The easiest way to run it locally is as a Docker container and then connect frontend web apps to it. This guide assumes that you know how to run Docker containers on your machine.
2. Please watch this video to run corteza-server as Docker container. As instructed in the video copy docker-compose.yaml and .env file from https://docs.cortezaproject.org/corteza-docs/2021.9/devops-guide/offline-deployment/multi-mysql.html.
3. You can also disable serving web app from Docker as we will be running web apps from the source. In .env file change HTTP_WEBAPP_ENABLED=false
4. Now your corteza-serve should be running on 127.0.0.1:18080 or at the specified domain in .env file on local.cortezaproject.org:18080
5. Check if everything is OK – http://127.0.0.1:18080/version or http://local.cortezaproject.org:18080/version

Step 2: run corteza-webapp- from source code

There are many Corteza web apps available such as corteza-webapp-admin, corteza-webapp-workflow,… All these web apps use two other repositories, corteza-js and corteza-vue, as dependencies, which have to be built and linked. Web apps such as corteza-webapp-admin are linked to corteza-vue and corteza-js. The corteza-vue repository is linked only to corteza-js.

2a: build corteza-js

1. Download or clone repository from https://github.com/cortezaproject/corteza-js
2. Run yarn command to install all packages
3. Run yarn build to build a fresh bundle
4. Run yarn link so that corteza-js becomes linkable

2b: build corteza-vue

1. Download or clone repository from https://github.com/cortezaproject/corteza-js
2. Run yarn link @cortezaproject/corteza-js so that corteza-js becomes dependency
3. Run yarn command to install all packages (Nodej.js version 13 installs without errors)
4. Run yarn build to build a fresh bundle
5. Run yarn link so that corteza-vue becomes linkable

2c: run the web app

1. Download or clone repository of available web apps. All apps are run the same way. https://docs.cortezaproject.org/corteza-docs/2021.9/developer-guide/web-applications/index.html
2. Create the config.js file from config.example.js. Run cp public/config.example.js public/config.js for Linux, or in public folder run copy config.example.js config.js for Windows
3. Set the API in the config.js file
4. Run yarn link @cortezaproject/corteza-js & yarn link @cortezaproject/corteza-vue so that corteza-js and corteza-vue become dependencies
5. Run yarn command to install all packages (for corteza-webapp-one Nodej.js version 13 installs without errors. For other web apps Node.js 14 is recommended)
6. Run the yarn serve command to start the web application
7. When running the web app from localhost, it will redirect you to the sign-in/sign-up page served from server
8. Create a new account. After successful signup, you are redirected to a web app running on localhost. To make sure that your user is admin and is able to use web apps with all features run docker-compose exec server /corteza/bin/corteza-server roles adduser super-admin your.user@something.com
   

Troubleshooting

If you see a blank page like below, window. Corteza API might be set wrong. To solve this. please refer to 2c step, point 3.