Openstad
Search
⌃K

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. Be aware submodules in git work a bit different then regular git repositories.
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.
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 databases

The setup script will initialize the databases, i.e. create the tables, but it does expect the 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
  • 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/.
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.

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. 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. 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. 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.
​
Previous
Architecture
Next
Deploying to production
Last modified 1mo ago