Welcome to the Petra Wiki summarizing [development](Development), [manual deployment](Deployment/Manually.md) and [CI/CD deployment](Deployment/CI-CD.md) in case something goes wrong or needs an upgrade. Otherwise, the stack should be deployed automatically by the the gitlab runners already configured. In case of a server restart, the docker stack restarts automatically. ## Architecture ![image](uploads/9dec4429bd8c7f2a448a5ac9be9f9109/image.png) ## URLs These are the URLs that will be used and generated by the project. ### Development Development URLs, for local development. Frontend: http://localhost Backend: http://localhost/api/ Traefik UI: http://localhost:8090 ### Endpoints ``` $ flask routes Endpoint Methods Rule --------------------- ---------------------- ----------------------- auth_login POST /api/auth/login auth_logout POST /api/auth/logout auth_refresh GET /api/auth/refresh auth_register POST /api/auth/register auth_token GET /api/auth/token auth_user GET /api/auth/user backlog_endpoint GET /api/board/backlog board_endpoint GET, PUT /api/board cycles_endpoint DELETE, POST, PUT /api/cycles main GET / matrix_endpoint GET /api/matrix module_endpoint DELETE, GET, POST, PUT /api/board/module progress_endpoint GET /api/progress publications_endpoint GET /api/publications root GET /api/ route_frontend GET / settings_endpoint GET, POST /api/settings static GET /static/ task_endpoint DELETE, GET, POST, PUT /api/board/task upload_endpoint POST /api/upload upload_filename GET /api/uploads/ verify_token POST /api/verify-token ``` ## Docker Containers All docker containers are stored at `Packages & Registries -> Container Registry` with the latest tag `prod` ## Environment Variables The docker stack requires a set of environment variables for maximum flexibility as specified in `Settings -> CI/CD -> Variables`. For example, to change the database, simply change the `DATABASE_NAME` key to the new name and rebuild the stack. * `CI_JOB_TOKEN`: deploy tokens from `Settings -> Repository -> Deploy Tokens` (read and write access) * `CI_REGISTRY`: `gitlab.lrz.de:5005` * `DATABASE_IP`: the database ip address * `DATABASE_NAME`: the database name * `DATABASE_PASS`: the database password * `DATABASE_PORT`: the database port * `DATABASE_USER`: the database username * `HOST_UPLOAD_FOLDER`: `/home/petra/upload` by default but can be different, create folder first * `JWT_SECRET_KEY`: [long random string of bytes](https://flask-jwt-extended.readthedocs.io/en/stable/options/#JWT_SECRET_KEY) # FAQ
Q: In case of a new Synology, how to connect Petra to it? The backend container connects via SQLAlchemy to the database with credentials from environment variables. During container build the Gitlab runners use the environment variables explained above i.e. `Settings -> CI/CD -> Variables`. Now, to change the related database credentials, e.g. the database ip, apply the following changes: 1. Enter new credentials by changing the values at `Settings -> CI/CD -> Variables` 2. Trigger the container build by committing changes to the code (adding whitespace somewhere should be enough) 3. Optionally: If the **old** database is still available, perform a backup of the tables and relationships and insert into the new database. Otherwise continue with (*). 4. Register a new team to Petra and verify via phpMyAdmin if the new team was written to table `team`. (*) If no backup is available, ssh into the server and enter the backend container via `docker exec -it bash` to perform a `flask db upgrade` as explained in the [wiki](Development/Database).
Q: In case of a power loss or server restart, what happens with Petra? If the Petra server performs a power cycle the docker stack restores its state. Simply speaking: Containers restart automatically without any further assistance. Petra is back online within several minutes.
Q: How to access the docker containers? The containers are stored at `Packages & Registries -> Container Registry` and it is easy to [use images from](https://gitlab.lrz.de/help/user/packages/container_registry/index#use-images-from-the-container-registry) and [build and push images to] the Container Registry. Authentication with access tokens is required.
Q: How to change text or headings within the frontend? To change values in the frontend, within the repository navigate to `petra-web/frontend/src/{components, views}` depending on the texts location and click on a `*.vue` file. Next, click on `Web IDE`, perform changes on the right and click 'commit' on the lower left. Enter an appropriate commit message, e.g. what you've changed, select 'Commit to master branch' and click 'Commit' again. This triggers the Gitlab pipeline building new containers to store in the Gitlab Container Registry. The Petra server downloads these new containers from the registry and deploys them according to the docker stack.
Q: How to export data from the DB? A convenient way to access the database is phpMyAdmin using the same credentials as the backend. There, it is possible to export the database as SQL, CSV or CSV for MS Excel. For this, click on `petradb` on the left hand side and then `Export` on the navbar. Select your desired format and click 'Go'. With phpMyAdmin it is also possible to perform queries and mutating entries.
## Troubleshooting Q: If the tool does not behave properly, how and where start to troubleshoot? If the frontend is not responding, `ssh` into the server and check if the docker stack is running, i.e. ```bash petra@petra-server:~$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 3d89be7fd9e8 traefik:v2.2 "/entrypoint.sh --pr…" 8 hours ago Up 8 hours 80/tcp petra-prototyping-de_proxy.1.rf85e3729e2jdh6nc1z50jv8r a4b2f4419399 gitlab.lrz.de:5005/martinspacheco/petra-web/backend:prod "/entrypoint.sh /sta…" 8 hours ago Up 8 hours 80/tcp, 443/tcp petra-prototyping-de_backend.1.uvynyzg7ws5pobx22nnfanfvm 0e18c6cebe13 gitlab.lrz.de:5005/martinspacheco/petra-web/frontend:prod "nginx -g 'daemon of…" 8 hours ago Up 8 hours 80/tcp petra-prototyping-de_frontend.1.r1t1s42ob7eczwpbvil9nykx4 801a434c484d traefik:v2.2 "/entrypoint.sh --pr…" 8 hours ago Up 8 hours 80/tcp stag-petra-prototyping-de_proxy.1.ao3t55v1mssr4sfq9gwvbo5i1 c8d4a5d72f5e gitlab.lrz.de:5005/martinspacheco/petra-web/frontend:stag "nginx -g 'daemon of…" 8 hours ago Up 8 hours 80/tcp stag-petra-prototyping-de_frontend.1.39lyqxksmrzjo7h4s5zh71jsp 9ad147412346 gitlab.lrz.de:5005/martinspacheco/petra-web/backend:stag "/entrypoint.sh /sta…" 8 hours ago Up 8 hours 80/tcp, 443/tcp stag-petra-prototyping-de_backend.1.3u4pjjqzu657vo7ewfliiacmx 4ce9f275cdce traefik:v2.2 "/entrypoint.sh --pr…" 8 hours ago Up 8 hours 80/tcp traefik_traefik.1.vir6fmhw2gf2eu0fj3zeax0hi 5f2ed06187f3 gitlab/gitlab-runner:latest "/usr/bin/dumb-init …" 2 months ago Up 3 days gitlab-runner gitlab-runner ``` or ```bash petra@petra-server:~$ docker stack ps petra-prototyping-de ID NAME IMAGE NODE DESIRED STATE CURRENT STATE ERROR PORTS uvynyzg7ws5p petra-prototyping-de_backend.1 gitlab.lrz.de:5005/martinspacheco/petra-web/backend:prod petra-server Running Running 8 hours ago r1t1s42ob7ec petra-prototyping-de_frontend.1 gitlab.lrz.de:5005/martinspacheco/petra-web/frontend:prod petra-server Running Running 8 hours ago rf85e3729e2j petra-prototyping-de_proxy.1 traefik:v2.2 petra-server Running Running 8 hours ago ``` where the `backend`, `frontend`, `consul` and `traefik` containers should be running. If they are all up and running, observe the containers logs via ```bash $ docker service logs ``` with `` from the previous command.