Getting started

These instructions are meant for running the openstad servers locally.

The are 5 different node servers working together. To make it easier to get started quickly and not manually configure every server, we made an overlaying git that bundles the 5 servers and added a few node scripts to install and run them with just a few commands.


  • NodeJS > v10
  • Mysql
  • Mongodb

1. Checkout openstad-app git repo

We've bundled our 5 nodejs servers in one git repo openstad-app with git submodules. Be aware submodules in GIT work a bit different then regular git repositories.

After checking out the repo, the git submodules need to be pulled separately, this is one way of doing that:

git submodule update --init --recursive

After this you will see 5 directory, these all container autonomous node servers. These can be run and managed separately, but it's easier to use the scripts provided in the root level.

It might however be useful for debugging purposes to run them separately every now and then, in this case the values from app.js should be copied to the .env of the server you are trying to run (the root file in the .env uses different keys).

2. Create an .env file

First create the .env before installing everything. There is an .env.example in the root openstad-app repo. Copy it and rename it to .env in the same folder.

Make sure the MySQL credentials are correct. For the rest the defaults don't have to change.

By default this will run the CMS at http://localhost:4444/.

A login token will be generated by following env value: AUTH_FIRST_CLIENT_LOGIN_CODE.

5. Install the node_modules

There is a script to install all the node_modules for 5 servers at once. It's also possible to run the npm i command separately in every sub git folder.

node npm-install.js

6. Create the MySQL databases

Create the MySQL databases manually, by default these are named in the .env file: image, api and auth.

7. Create and fill tables for the databases

Install knex globally:

npm install knex -g

The following script install and fill all 3 databases:

node install-databases.js

Warning: currently this script is not safe to run twice and will fail. In case you want to run again, easiest is to manually delete all tables.

In case you get an error that password is not supported:

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password'

If you are running a version of MySQL above version 5 then you will most likely get the following error:

Unhandled rejection SequelizeDatabaseError: FUNCTION api_test_script.GeomFromText does not exist

In this case add following to the .env file:


8. Run the servers

Now run all servers with:

node app.js

That should be it :)

What to expect

By default the CMS is found at http://localhost:4444. Login via /login, with the login token set it the .env. (after creating the mysql tables changing it in .env won't make a difference).

The admin panel is found at http://localhost:7777. It is of limited use locally because it allows for copying sites and managing setting per site and it expects dynamic DNS settings. For a kubernetes cluster it also manages the Ingress host and SSL settings. If you want to run multiple local sites it's easiest to add a few urls that point to in the etc/hosts file of your machine then it's possible to create them in the admin panel, be aware it's needed to at the port number: http://local.budgeting:4444

results matching ""

    No results matching ""