Deployment of base Applications#

Before you start to deploy anything, make sure you meet all the Requirements.

General setup procedure#

The general principle for any setup is to deploy the most upstream service first, and the nginx service at the end. So a common setup procedure just for Portfolio would take the following order:

  • set up baseauth

  • set up portfolio-backend

  • set up portfolio-frontend

  • set up nginx

If you also want to set up Showroom, you would squeeze the setup of showroom-backend and showroom-frontend in after Portfolio is set up, but before nginx is set up.

Multi-server setup procedure#

On a multi-server-setup, where baseauth, Portfolio and Showroom are all set up on different machines you would do the following:

  • set up machine with baseauth:

    • set up baseauth

    • set up nginx

  • set up machine with Portfolio:

    • set up portfolio-backend

    • set up portfolio-frontend

    • set up nginx

  • set up machine with Showroom:

    • set up showroom-backend

    • set up showroom-frontend

    • set up nginx

In this scenario you will have to update the nginx config of that machine, that serves as the initial entry point for user requests. But you could even set up a fourth machine only with nginx, which then serves as the first reverse proxy. All other nginx containers on the other machines are only reverse proxies for the single services they are hosting.

Single-Server-Setup of Portfolio and Showroom#

In this section we’ll walk you through a setup of Portfolio and Showroom on a single machine.

For this scenario we will use a machine base-preview, which is publicly accessible at base-preview.uni-ak.ac.at. So wherever any of these are mentioned in the procedure below, you will have to replace it with your machines name/DNS entry. Also, we will not use an external authentication backend, but Django’s internal user model. Configuring external authentication backends like LDAP, CAS, or Shibboleth is highly specific to your own setup, so we will try to handle this in separate tutorials in the future. You can always start out with the default, and later add or switch to your organisation’s authentication backend.

If you prefer a video walkthrough, there is a screencast based on this scenario: Screencast: base Portfolio Single Server Setup

Step 1: baseauth#

Following the above-mentioned general procedure, we will start with baseauth fist. So we’ll clone the repo first.

cd /opt/base
sudo -u base git clone https://github.com/base-angewandte/baseauth.git

Following “Production” section of the install section of the baseauth docs, we create the .env and src/baseauth/.env files and adapt the values according to the configuration section of the baseauth docs. For the most minimal setup we need to at least set the SITE_URL to DNS entry under which the new system is available, as well as the BASEAUTH_DB_PASSWORD, to a strong random password (e.g. generated by pwgen -s 32 1). If we did everything right, the only thing left to do is to start the services with sudo make start init restart-gunicorn. That’s it, we are done with our first service.

If you want to check if baseauth is really up and running to expectations, you can do the following:

# check if all containers are up and running
sudo docker ps
# this should show you at least for baseauth-* containers where the STATUS is "Up [... for some time ...]"
# for the baseauth-django container you should also see, that it has the port 8000/tcp opened.

Generally the best sign, that everything is working as expected in our backends is, if the migrations show a green OK, after the point where make init (or make start init restart-gunicorn in this specific case) ran.

But you can also try to make an actual HTTP request to the Django service:

# let's find out the container's IP address
docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' baseauth-django
# and check whether the HTTP server is responding
curl 172.18.0.2:8000  # replace with the IP your got from the last command
# this should return a 400 Bad Request response, as per default baseauth will only allow
# requests directed to base-preview.uni-ak.ac.at. check the logs/application.log for details.

So, if you “successfully” get back this 400 Bad Request response, at the current stage everything should be fine. If you want to dig deeper, you will need to adapt the src/baseauth/.env settings to allow for another hostname. Or wait, until we’ve set up everything and nginx is running, then we can send requests to the proper URI.

While the install section now says to continue with nginx (assuming baseauth is the only service to be set up on the machine), we will now continue with the other services, to set up nginx at the end.

Step 2: portfolio-backend#

Let’s check out the portfolio-backend:

cd /opt/base
sudo -u base git clone https://github.com/base-angewandte/portfolio-backend.git

Now we can follow its Installation Guide. The procedure will be quite similar to baseauth: 1) create the .env files and adapt the values 2) start the service. Only in case of Portfolio the settings become a bit more complex, so you might want to take a closer look at the Configuration section of the docs. But for a minimal first setup (with Showroom not yet activated), we should be fine with only adopting the PORTFOLIO_DB_PASSWORD in .env and the SITE_URL in the src/portfolio/.env file.

So let’s spin up the services with sudo make start init restart-gunicorn.

Similar to baseauth you can check for the container status with docker ps.

Step 3: portfolio-frontend#

If everything is up and running, we can continue to set up portfolio-frontend:

cd /opt/base
sudo -u base git clone https://github.com/base-angewandte/portfolio-frontend.git

Following its setup and project and production setup notes, we copy the .env file to .env.local and adapt the values as needed. At least the VUE_APP_BACKEND_BASE_URL needs to be changed to the URL of our new machine. The VUE_APP_HEADER_URL_TERMS and VUE_APP_HEADER_URL_NOTICE can be set to any URL that displays your Terms of use and the Site notice. If you set these to an empty string, those links will not be shown in the frontend’s footer.

Once the settings are adapted, we can build the frontend with sudo make build-app. In this case we don’t even need to check for running containers afterward, as the built code will be included statically by nginx.

While we still want to set up Showroom, we now really want to make sure everything is up and running. So we’ll now continue with the nginx setup. We can then later set up the Showroom components and reconfigure nginx, and activate Showroom in Portfolio too.

Step 4: nginx#

Again, we’ll first start by checking out the nginx repo:

cd /opt/base
sudo -u base git clone https://github.com/base-angewandte/nginx.git

Following the deployment notes in the repo’s readme, we create the .env file and adapt the values. This means usually just adopting the BASE_HOSTNAME to the hosts FQDN (in this scenario base-preview.uni-ak.ac.at), and to set the LETSENCRYPT_EMAIL as a contact for certificate-related issues.

The main nginx configuration then happens in the docker-compose.override.yml file, which we create from its skeleton version. Here we activate baseauth and Portfolio by uncommenting the corresponding environment directives. As we currently also only have Portfolio running, we can also adapt the INDEX_REDIRECT to /portfolio.

Hint

Do not forget to uncomment the environment: line itself. This is a common pitfall. If you forget to do that, an error like “yaml: line 2: did not find expected key” will be produced, once you execute make start.

It is now time create the Let’s Encrypt certificates with sudo make init and then start up nginx with sudo make start.

Step 5: create admin user#

If everything is up and running (check with sudo docker ps), we now are able to access our new installation at https://base-preview.uni-ak.ac.at.

We will be redirected to the Portfolio frontend, and from there immediately to baseauth, as Portfolio only allows access by authenticated users. So far we have not a single account. So let’s create a first superuser account on baseauth, which will then be able to add more user accounts.

cd /opt/base/baseauth
sudo docker-compose exec baseauth-django python manage.py createsuperuser

We will also need to reconfigure the src/baseauth/.env file for the DJANGO_SUPERUSERS. If you before created an account with the username admin, then set it to DJANGO_SUPERUSERS=(admin). Afterwards restart the Django service with sudo make restart-gunicorn.

You can now use this account right away to create entries in portfolio. If you want to manage the user accounts of baseauth, you need to go to its Django admin interface, by adding /admin/ to the base url of baseauth. In this scenario this would be: https://base-preview.uni-ak.ac.at/auth/admin/.

That’s it for now. This walkthrough will be extended by sections on how to add Showroom within the next few weeks.