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.

Prerequisites:

1. Checkout openstad-app git repo

We've bundled our 5 nodejs servers in one git repo openstad-app with git submodules. 

git clone https://github.com/openstad/openstad-app

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

cd openstad-app
git submodule update --init --recursive

After this you will see 5 directories, each of which contains an autonomous node server. These servers can be run and managed separately, but it's easier to use the scripts provided in the root level.

2. Create MySQL databases

The setup script will initialize the databases, i.e. create the tables, but it does expect the MySQL database to exist. In SQL:

CREATE DATABASE `openstad-api`;
CREATE DATABASE `openstad-image-server`;
CREATE DATABASE `openstad-oauth-server`;

Do not forget to make these databases accessible by the user from the .env file: 

CREATE USER `USERNAME`@`%` IDENTIFIED BY 'PASSWORD';
GRANT ALL ON `openstad-api`.* TO `USERNAME`@`%`;
GRANT ALL ON `openstad-image-server`.* TO `USERNAME`@`%`;
GRANT ALL ON `openstad-oauth-server`.* TO `USERNAME`@`%`;

3. 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, using the username and password from the previous step

  • Change the AUTH_FIRST_CLIENT_LOGIN_CODE - this is a code that will be used later to login; choose any code you like.

  • Outgoing email is used for login on sites and feedback to users. It can be circumvented, but only if you know what you are doing

The rest of the defaults should suffice in most situations.

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

A login token will be generated following the given value for AUTH_FIRST_CLIENT_LOGIN_CODE.

4. Run setup

First initialize the node modules:

npm install

Now the command

npm run setup

will create the necessary configuration, install npm modules and initialize the DB. It should be smart enough to be run again: existing databases will then not be overriden.

Note: if you see an arror like use this SQL command to fix this:

ALTER USER 'USERNAME'@'%' IDENTIFIED WITH mysql_native_password BY 'PASSWORD'

5. Run the servers

Use

npm run start

to start the servers.

What to expect

Five servers should now be running. You could try and use them with the description below, but preferably you now go to step 5.

By default the CMS is found at http://localhost:31401. It uses Basic Authentication with username openstad and password openstad. Login via http://localhost:31401/login with the login token set in the .env file as AUTH_FIRST_CLIENT_LOGIN_CODE. Note: this value was only used during the creation of the mysql tables. Changing it afterwards in .env will not change the login token.

The admin panel is found at http://localhost:31404. 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 127.0.0.1 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:31401

6. Setup a reverse proxy

To make the above a bit more usefull you may want to setup a reverse proxy server to make the sites and servers available.

If you the ran npm run setup command above a file nginx.config.example was created in de openstad-app directory. Use this to setup your local nginx server by copying this file to the sites-available directory. Create a link in sites-enabled, and restart nginx.

The admin server should now be available on http://openstad-admin.base-domain . If you create a new site here it will by default be available on http://name-of-site.openstad-cms.base-domain

You will probably need an entry in your /etc/hosts file:

127.0.0.1 openstad-api.openstad.local openstad-oauth.openstad.local openstad-image.openstad.local openstad-cms.openstad.local .openstad-cms.openstad.local openstad-admin.openstad.local

Use the admin panel to create a new user and make that user administrator on the new site.

Notes

  1. The site you created in step 5 has a basic auth setup. The login information can be found in the admin panel, under settings/password protection

  2. if your server does not resolve the url http://name-of-site.openstad-cms.base-domain correctly changes you make in the admin panel (like the just mentioned basic auth) may not be directly available. Restarting the servers will help, but using existing DNS names would be nicer.

  3. This setup is of course not secure. Remove the FORCE_HTTP param from the .env file and run npm run setup again. Then setup your proxy server to use https instead of http. If you already created sites then update the url for those sites.

  4. It might be useful for debugging purposes to run the servers 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).

PreviousArchitectureNextDeploying to production

Last updated