README.md 4.34 KB
Newer Older
jfriedli's avatar
updated  
jfriedli committed
1
# MAT2 Quasar Frontend (PWA)
jfriedli's avatar
jfriedli committed
2
![](mat-frontend.gif)
3 4


jfriedli's avatar
jfriedli committed
5
This is a frontend for [MAT2-web](https://0xacab.org/jvoisin/mat2-web).
jfriedli's avatar
jfriedli committed
6

7 8 9
# How To Deploy

## Manual Deployment with custom build
jfriedli's avatar
jfriedli committed
10

11 12 13
1) Install dependencies: `yarn install`
2) Export env variable `MAT2_API_URL_PROD` which points to your [MAT2-web backend](https://0xacab.org/jvoisin/mat2-web)
 e.g. `MAT2_API_URL_PROD=https://mybackend.gnu/`. Alternatively you can define the URL in the `quasar.conf.js` file
jfriedli's avatar
jfriedli committed
14
 on the following line: `API_URL: JSON.stringify(process.env.MAT2_API_URL_PROD)` and change it to:
15 16 17 18
 `API_URL: 'https://mybackend.gnu/'`
3) `quasar build -m pwa` (Must have installed the quasar cli)
4)  Copy the files from `./dist/pwa` to your hosting.
5) Enjoy :)
jfriedli's avatar
jfriedli committed
19

20
## Deployment with Docker
jfriedli's avatar
updated  
jfriedli committed
21
**Registry Frontend:** https://0xacab.org/jfriedli/mat2-quasar-frontend/container_registry
22

jfriedli's avatar
updated  
jfriedli committed
23 24 25
**Registry Backend:** https://0xacab.org/jvoisin/mat2-web/container_registry


jfriedli's avatar
jfriedli committed
26 27
On every new tag/master a new Docker Container is built. To configure
its API Url you have to pass the environment variable
28 29
`MAT_API_HOST_PLACEHOLDER` which points to your backend. Make sure
it has a slash at the end ;).
30
Internally this replaces a placeholder string in the prebuilt JS/HTML/CSSS files and starts an NGINX server.
31

jfriedli's avatar
jfriedli committed
32 33
**Example:**
Build the container:
34
`docker build --build-arg MAT2_API_URL_PROD='$MAT_API_HOST_PLACEHOLDER' -t mat2frontend .`
jfriedli's avatar
updated  
jfriedli committed
35
Or alternatively get it from the registry prebuilt.
36 37 38 39

Then run it:
`docker run -it -e MAT_API_HOST_PLACEHOLDER='https://mybackend.gnu/' -p 80:80 mat2frontend`

40
# Contribute
jfriedli's avatar
jfriedli committed
41

42 43
## Up and Running for development
To start developing clone this repository and run `docker-compose up`. If
jfriedli's avatar
jfriedli committed
44
this was successful you can access the app on:
45
`localhost:8080`. This will start the backend as well
jfriedli's avatar
jfriedli committed
46
 using it's latest docker image. Codechanges will trigger an instant update in your browser.
47
 If you update/add/remove dependencies you'll have to rebuild the container: `docker-compose up --build`.
jfriedli's avatar
jfriedli committed
48 49


50 51 52 53 54 55 56 57 58 59 60 61 62
 If you don't want to use `docker-compose`.
 1) `yarn install`
 2) `yarn global add @quasar/cli`
 3) `quasar dev`

Make sure you have a running backend instance that you can reference in the `quasar.js` file.

## Branching Workflow
For solving an issue you'll start by creating a branch and merge request for it.
When it's done you'll make a merge request for from your branch into the `develop` branch.

| Branch   |  Description  |
| ---------|:-------------:|
jfriedli's avatar
jfriedli committed
63
| Develop  | The develop branch MIGHT contain non *operational code |
64 65 66 67
| Master   | The Master branch MUST contain *operational code |

*operational: This means the code itself contains only working features and finished
 tasks that have been tested and are known to be working.
jfriedli's avatar
jfriedli committed
68

69 70 71
 ### Tags
 We do use tags to mark releases. A tag SHOULD reference the master branch.
 On tag creation you have to submit a changelog.
jfriedli's avatar
jfriedli committed
72

73 74 75 76 77 78
 ### Configuration
 To set the base url of the backend you have to define
 `MAT2_API_URL_DEV` for dev builds and `MAT2_API_URL_PROD`
 for production builds. If you use the docker environment
 this is customizable in the `docker-compose.yml` file.
 If none of these are set it will default to `http://localhost:5000/` (slash at the end).
jfriedli's avatar
jfriedli committed
79
 To make sure the open graph tags are working you need to set the
jfriedli's avatar
jfriedli committed
80
 env variable `FRONTEND_URL_PLACEHOLDER=https://matweb.info/` to the domain name you're
jfriedli's avatar
jfriedli committed
81
 hosting the frontend.
82 83 84

## Translations
We'd love to receive any translation merge requests :).
jfriedli's avatar
jfriedli committed
85

86 87 88
## Dependency Management
We do use renovate which checks every night for updates and creates automated merge request.

jfriedli's avatar
jfriedli committed
89 90 91
## E2E Tests
Run the E2E tests: `quasar test --e2e cypress`.
We use the cypress.io framework for testing.
jfriedli's avatar
jfriedli committed
92
The E2E tests are run during the ci phase.
jfriedli's avatar
jfriedli committed
93

jfriedli's avatar
jfriedli committed
94 95 96 97 98 99 100 101 102 103 104 105 106

## Docker
To build the prodcution image: `docker build -t mat-web-frontend .`
The nginx runs as non privileged user.

To start the container: `docker run -ti -p8080:8080 --security-opt no-new-privileges --security-opt seccomp=seccomp.json --read-only --tmpfs /var/www/html  --tmpfs /tmp  mat-web-frontend:latest`
This starts it on your host machine on port 8080.

## Podman
Build: `podman build -t matweb-frontend .`

Run: `podman run -ti --security-opt=no-new-privileges --read-only -p8080:8080  --tmpfs /var/www/html  --tmpfs /tmp --security-opt no-new-privileges --security-opt seccomp=seccomp.json  matweb-frontend`

107 108
## Design
You can find the design documents here: https://0xacab.org/jfriedli/mat2-quasar-frontend/-/wikis/Design-Documents