hubbel

Setup

Docker

We provide two Docker files:

• one for the backend and website (Dockerfile)
• one for the hybrid hubbel website (Dockerfile.hubbel)

Example usages

docker build -f Dockerfile . -t hubbelwebsite

docker build -f Dockerfile.hubbel . -t hubbelhybrid

docker run -d --name=hubbel-website --network your_network --restart=always -p 8083:8080 -v /var/hubbel/attachments:/app/backend/public/attachments -v /var/hubbel/profilePictures:/app/backend/public/profilePictures -e ENVIRONMENT="production" -e DB_HOST="mysql_host" -e DB_USER="your_db_user" -e DB_PASSWORD="your_db_password -e DB_DB="hubbel" -e JWT_TOKENKEY="yourtoken" -e JWT_ALGORITHM="HS256" -e HUBBEL_EMAIL="hubbel@hubbelmail.de" hubbelwebsite

docker run -d --name=hubbel-hybrid --network your_network --restart=always -p 8084:8080 hubbelhybrid

Without docker, e.g. for local development

Prerequisites

This project requires Node.js, npm and MySQL to be installed on your machine.

Node.js + npm

Follow the instructions provided on this page: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm

MySQL

Download the installer from this page: https://dev.mysql.com/downloads/installer

1. Use the bigger install file.
2. During the installation, install MySQL Workbench.

Additionally, you may want to install the MySQL notifier to easily start and stop your MySQL server.

Setup notes

For setting up the database, refer to Import MySQL dump. For setting up the environment variables, refer to Adjust Configurations. Since the hubbel-hybrid app tries to log into an existing "hubbel" account, you first have to set up the backend using a strong JWT token, then register a hubbel account on the website with the email address you provided as "HUBBEL_EMAIL" environment variable.

Import MySQL dump

To be able to start the project, you need to have a functioning MySQL server with the correct schema running. A dump of such schema is provided in /database_queries/hubbel_20220921_novalues.sql.

1. To import it, connect to your MySQL server using the MySQL Workbench and credentials you provided during the installation of your MySQL server. Note: The MySQL server needs to be running, which can be achieved using the MySQL Notifier.
2. Once connected to your MySQL server, change the tab to "Administration" in the bottom left.
3. Then, use Management > Data Import/Restore > Import from Disk.
4. There, import the hubbel_20220921_novalues.sql. Note: Sometimes, MySQL Workbench hides certain UI elements at the bottom. You may need to adjust some of the container sizes inside MySQL Workbench like the "Output".
5. Afterwards, copy and paste the contents of other sql files in the /database_queries directory and apply them in chronological order using the lightning bolt icon (see /database_queries/howto.jpg), if there are any such sql files.

Note: The dump does not include user files like attachments. We may provide some in the future.

Adjust Configurations

In order to hide some secrets like passwords, we use environment variables. You need to set them for your machine.

1. If you are using docker, you can change the variables in the Dockerfiles directly. Without Docker, copy /backend/.env.template in /backend and name the copied file .env.
2. Change all entries according to your specifications. Some hints:

• The ENVIRONMENT should be "development" during development and "production" when deployed on a server for public usage.
• Use your own database specifications for DB_USER and DB_PASSWORD, i.e. the one you set during the installation of MySQL on your system.
• Generate a JWT_TOKENKEY or ask a colleague for an existing one.
• The BACKEND_PORT is where your Node.js/Express.js server is running.
• HUBBEL_EMAIL is the email address of your hubbel account on the hubbel website, i. e. the one that hubbel posts are associated with.
• POSTCARD_PREPRINT_TEXT_TOP, POSTCARD_PREPRINT_NAME_TOP, and POSTCARD_PREPRINT_NAME_BOTTOM are texts that are pre-printed on your postcards and that should not be visible on the digital postcards as part of the user text, i. e. it should be discarded after the OCR.

3. Also, for the OCR to work, you need a Google Vision authentication token and place it in \auth.json.

Do the same for /client/.env.template and /client-hubbel/.env.template.

• VUE_APP_BACKEND_PORT has to be the same as the one in /backend/.env.
• VUE_APP_BACKEND_URL is necessary in case your frontend is deployed on a server different from your backend. You don't have to change this locally.
• VUE_APP_SCANNER_URL_PORT is where your raspberry pi is running in case you have one. Again, locally this is not applied as we assume you don't have a raspberry pi locally.
• VUE_APP_IS_LOCAL_DEBUG_OCR is used to skip scanning images and use default values instead, in case Google Vision is unavailable. Locally, we assume you do not have a raspberry pi and skip scanning postcards anyways, but you may still want to test your OCR. If set to false, OCR will be skipped and default values will be used. If set to true, Google Vision OCR will be used and a file stored in your backend folder will be used.
• VUE_APP_HEARTBEAT_INTERVAL is the interval in minutes for Vue.js to send a short sign of life to the backend. This is used to determine if the hubbel is still running, albeit not the best solution.
• VUE_APP_HEARTBEAT_IDENTIFIER is an identifier for the above-mentioned sign of life. This identifier is not per machine, but per code deployment. So if the same code is used on different machines, the identifier would be the same for both of them. We might want to use cookies instead of this env.

Install Dependencies

In your IDE, open the terminal, make sure you're in the root directory of the project and install all dependencies of the project using

npm install  

Navigate to /backend, /client, and /client-hubbel and do the same in all of them.

Development workflow

To start the project, navigate to the root directory of the project and use the following command

npm run both  

That will start both the backend (MySQL needs to be running) and the client. After a short compilation time, the terminal should state that the app is running on localhost:8080. Alternatively, you can start the backend and the frontend independently using

npm run backend  

and, in a separate terminal

npm run frontend-website  

or

npm run frontend-hubbel  

You can also start both frontends simultaneously in two different terminals. The second frontend will then be served on port 8081.

Before you push any code, please run ESlint by using the following command in the root directory:

npm run lint

This will not change the layout of the scss-files in /client-shared yet, so you may want to auto-format that code using your IDE.

Customization

If you forked this repository, you may also want to make some changes. To minimize the chance for merge conflicts, we added some basic functionality for customizing and overriding certain aspects of the code.

• To change styles, you may want to check /client-shared/scss/override. To change colors and sizes, override the default values in variables.scss. To override vuetify variables, add or change the values in vuetify_variable.scss. To override more complex styles or to add new styles, add your style code in custom.scss.
• To change views and components (including their texts), you may not override the files directly, but rather copy them into /views/override) or /components/override using the original file name and then adjust the import statements for the corresponding files. An example is given with /client/src/views/Test.vue that is imported in /client/src/router/index.js.

If you think your changes should be in the main repository, feel free to open a pull request :)

Production

1: On the remote server (credentials are in Nextcloud), navigate to the root directory of the project: ~/hubbel

git pull  

If you're using docker, refer to the beginning of this document. Otherwise, read ahead.

If the package.json for /client or /backend changed, npm install the new modules in the respective directories using.

npm install  

To build the Vue.js frontend, run

npm run build-frontend-website  

To start the Node.js backend, run

cd backend  
pkill -f 'node app.js'  
nohup node app.js &  
exit  

Sometimes, the app.js service can not be started if it's still running, so we better kill it every time. Tip: You can create a bash script for restarting the backend, which will also prove helpful to restart it in case it crashes for other reasons.

License

This project is licensed under the EUPL, v1.2. See EUPL-1.2 (English) or EUPL-1.2 (German) for details.