This repository presents the reference implementation of a product data server as part of the product data network buildingenvelopedata.org. Before deploying this repository, machine can be used to set up the machine.

The API specification of the product data servers is available in the repository api. There is also a visualization of the API of a product data server.

This repository is deployed as the product data server of TestLab Solar Facades of Fraunhofer ISE.

If you have a question for which you don't find the answer in this repository, please raise a new issue and add the tag question! All ways to contribute are presented by CONTRIBUTING.md. The basis for our collaboration is decribed by our Code of Conduct.

1. Open your favorite shell, for example, good old Bourne Again SHell, aka, bash, the somewhat newer Z shell, aka, zsh, or shiny new fish.
2. Install Git by running sudo apt install git-all on Debian-based distributions like Ubuntu, or sudo dnf install git on Fedora and closely-related RPM-Package-Manager-based distributions like CentOS. For further information see Installing Git.
3. Clone the source code by running git clone git@github.com:building-envelope-data/database.git and navigate into the new directory database by running cd database.
4. Initialize, fetch, and checkout possibly-nested submodules by running git submodule update --init --recursive. An alternative would have been passing --recurse-submodules to git clone above.
5. Prepare your environment by running cp .env.sample .env, cp frontend/.env.local.sample frontend/.env.local, and adding the line 127.0.0.1 local.solarbuildingenvelopes.com to your /etc/hosts file.
6. Install Docker Desktop, and GNU Make.
7. List all GNU Make targets by running make help.
8. Generate and trust a self-signed certificate authority and SSL certificates by running make ssl. If you are locally working the the metabase and the database and if you need them to communicate over HTTPS, then instead of running make ssl, make the CERTIFICATE_AUTHORITY_* variable values in the .env file match the ones from the metabase, copy the certificate authority files from the directories ./ssl, ./backend/ssl, and ./frontend/ssl of the metabase project into the respective directories in the database project, and run the command make generate-ssl-certificate.
9. Generate JSON Web Token (JWT) encryption and signing certificates by running make jwt-certificates.
10. Start all services and follow their logs by running make up logs.
11. To see the web frontend navigate to https://local.solarbuildingenvelopes.com:5051 in your web browser, to see the GraphQL API navigate to https://local.solarbuildingenvelopes.com:5051/graphql/, and to see sent emails navigate to https://local.solarbuildingenvelopes.com:5051/email/.

In another shell

1. Drop into bash with the working directory /app, which is mounted to the host's ./backend directory, inside a fresh Docker container based on ./backend/Dockerfile by running make shellb. If necessary, the Docker image is (re)built automatically, which takes a while the first time.
2. List all backend GNU Make targets by running make help.
3. For example, update packages and tools by running make update.
4. Drop out of the container by running exit or pressing Ctrl-D.

The same works for frontend containers by running make shellf.

For information on using Docker in production see Configure and troubleshoot the Docker daemon and the pages following it.

1. Use the sibling project machine and its instructions for the first stage of the set-up.
2. Enter a shell on the production machine using ssh.
3. Change into the directory /app by running cd /app.
4. Clone the repository twice by running

   for environment in staging production ; do
     git clone git@github.com:building-envelope-data/database.git ./${environment}
   done
   

5. For each of the two environments staging and production referred to by ${environment} below:
   1. Change into the clone ${environment} by running cd /app/${environment}.
   2. Prepare the environment by running cp .env.${environment}.sample .env, cp frontend/.env.local.sample frontend/.env.local, and by replacing dummy passwords in the copies by newly generated ones, where random passwords may be generated running openssl rand -base64 32.
   3. Prepare PostgreSQL by generating new password files by running make --file Makefile.production postgres_passwords and creating the database by running make --file Makefile.production createdb.

1. Draft a new release with a new version according to Semantic Versioning by running the GitHub action Draft a new release which, creates a new branch named release/v*.*.*, creates a corresponding pull request, updates the Changelog, and bumps the version in package.json, where *.*.* is the version. Note that this is not the same as "Draft a new release" on Releases.
2. Fetch the release branch by running git fetch and check it out by running git checkout release/v*.*.*, where *.*.* is the version.
3. Prepare the release by running make prepare-release in your shell, review, add, commit, and push the changes. In particular, migration and rollback SQL files are created in ./backend/src/Migrations/ which need to be reviewed --- see Migrations Overview and following pages for details.
4. Publish the new release by merging the release branch into main whereby a new pull request from main into develop is created that you need to merge to finish off.

1. Enter a shell on the production machine using ssh.
2. Change to the staging envrionment by running cd /app/staging.
3. Deploy the new release in the staging environment by running make --file Makefile.production deploy.
4. If it fails after the database backup was made, rollback to the previous state by running make --file Makefile.production rollback, figure out what went wrong, apply the necessary fixes to the codebase, create a new release, and try to deploy that release instead.
5. If it succeeds, deploy the new reverse proxy that handles sub-domains by running cd /app/machine && make deploy and test whether everything works as expected and if that is the case, repeat all stages but this one in the directory /app/production (instead of /app/staging). Note that in the staging environment sent emails can be viewed in the web browser under https://staging.solarbuildingenvelopes.com/email/ and emails to addresses in the variable RELAY_ALLOWED_EMAILS in the .env file are delivered to the respective inboxes (the variable's value is a comma separated list of email addresses).

• Set up a GraphQL client with Apollo