Web Component

This is a web skeleton with a basic user login functionality.

Setup (Non-Docker)

Consult the README.md in the API and UI subdirectories.

Setup (Docker)

Note that the docker setup is configured for development by default. Traffic is served over unencrypted http. Production setups should, at a minimum, use encrypted https.

Docker Prerequisites

The docker and docker-compose commands must be available. If you're using older versions than specified, it might still work, it's just untested.

• Docker, at least v18.06
• Docker Compose, at least 1.17

Run

Make sure you're in the web component's root directory (where this README is located) and run:

docker-compose up

• The UI should be accessible at http://localhost:5000/.
• The API should be accessible at http://localhost:5000/api.

A default admin user is available with:

• Username: admin
• Password: admin

The default docker-compose up command will start the containers in the foreground, showing all log output directly. To exit, press Ctrl-c or whatever key combo your OS uses to send SIGINT.

Changes to the source files should be automatically reloaded on the running containers. In practice, frontend CSS sometimes don't go through properly, so you might need to manually refresh the page to see the changes. Some python errors, particularly syntax problems, can kill the reloader. In such cases, you can restart just the API container with:

docker-compose restart api

On the API side, two automatically generated interactive documention is available at:

• http://localhost:5001/docs, generated by SwaggerUI
• http://localhost:5001/redoc, alternative generated by ReDoc

Note the different port used, 5001 instead of 5000. This is the actual port that the API is running on. A reverse proxy is used to redirect traffic from http://localhost:5000/api to http://localhost:5001/. This was necessary in order to avoid CORS errors in the browser.

The reverse proxy status page is at: http://localhost:5002/

A web frontend to the Postgres database is available at:

• http://localhost:5003/, powered by Adminer, login information:
  • System: PostgreSQL
  • Server: api_db
  • Username: api_db
  • Password: api_db
  • Database: api_db

Execute Commands

To run arbitary commands, just replace <COMMAND> with what you wish to run:

docker-compose exec <SERVICENAME> <COMMAND>

Check docker-compose.yml for the service names you should use in place of <SERVICENAME>.

Example:

• To get shell access in the UI container, just execute bash

    docker-compose exec ui bash
  

Hard Reset

WARNING: This will remove all data and containers!

docker-compose down -v

Running in the Background

If you wish to run this in the background, without the live log output, add the -d option:

docker-compose up -d

To stop running:

docker-compose stop

To access the logs in this mode, run:

docker-compose logs <SERVICENAME>

Examples:

• API

    docker-compose logs api
  

• API's Database (Postgre)

    docker-compose logs api_db
  

Updating dependencies

API

First, follow the API README.md instructions for adding/updating dependencies.

If the app is currently running, shut it down. Rebuild the API docker image so it has the new dependencies using:

docker-compose build api

Then start it back up again.

Common Problems

• API calls are not going through (being redirected to the UI).

  You may need to add a / at the end of your API URL. http://localhost:5000/api/users/ will go to the API. http://localhost:5000/api/users will get redirected to http://localhost:5000/users/.

• CORS issue due to API and UI running separately.

  The docker-compose dev environment is using the Traefik reverse proxy to make it look like API requests are going to the same server as the UI. If this doesn't work for you or you need something simpler, you can specify allowed origins on the API side manually using this tutorial.