Authentik
This is an Authentik setup for development in order to make local testing for production behaviour as easy as possible including the authentication mechanisms.
Preperation
This package comes with an preconfigured authentic - which has its data mainly residing in a postgress database. The contents of this database is available in packed form.
To extract the database use:
./database.unpack.sh
+(Note: make sure the database is not running before executing this command)
`,7),c={href:"https://goauthentik.io/docs/installation/docker-compose#preparation",target:"_blank",rel:"noopener noreferrer"},p=t(`Start Docker
To start the authentik server and its services run:
docker compose up
+(Note: make sure to run this command in the authentik folder, since there is another docker-compose setup in the main folder)
User Credentials
`,5),u={href:"http://localhost:9000",target:"_blank",rel:"noopener noreferrer"},m=t(`To login you can use the superadmins credentials:
| description | value |
|---|---|
| username | akadmin |
| admin@dreammall.earth | |
| password | dreammall |
Publish changes
If you want to publish changes to the database you can use the following command to pack the database:
./database.pack.sh
+(Note: this assumes you are not root and sets the permissions of the database files via sudo) (Note: make sure to shut down the database first before you run the script)
`,6);function b(g,k){const s=r("ExternalLinkIcon");return o(),d("div",null,[l,a("p",null,[e("Alternatively you can not extract the database, which will start the service with an empty database. Use the "),a("a",c,[e("Docker Guide"),n(s)]),e(" from Authentik to get you going then.")]),p,a("p",null,[e("You can navigate to the now running authentik by opening "),a("a",u,[e("http://localhost:9000"),n(s)]),e(".")]),m])}const f=i(h,[["render",b],["__file","index.html.vue"]]),_=JSON.parse('{"path":"/authentik/","title":"Authentik","lang":"en-US","frontmatter":{},"headers":[{"level":2,"title":"Preperation","slug":"preperation","link":"#preperation","children":[]},{"level":2,"title":"Start Docker","slug":"start-docker","link":"#start-docker","children":[]},{"level":2,"title":"User Credentials","slug":"user-credentials","link":"#user-credentials","children":[]},{"level":2,"title":"Publish changes","slug":"publish-changes","link":"#publish-changes","children":[]}],"git":{"updatedTime":1713376945000,"contributors":[{"name":"Hannes Heine","email":"heine.hannes@gmail.com","commits":1}]},"filePathRelative":"authentik/README.md"}');export{f as comp,_ as data}; diff --git a/assets/index.html-BGnEJQJY.js b/assets/index.html-BGnEJQJY.js new file mode 100644 index 0000000000..0bcfd88034 --- /dev/null +++ b/assets/index.html-BGnEJQJY.js @@ -0,0 +1,15 @@ +import{_ as r,r as a,o as d,c as l,a as e,d as n,b as o,e as s}from"./app-DvhWSl6p.js";const i="/dreammall.earth/assets/dreammall-logo-BDPGqpR2.svg",c={},p=e("h1",{id:"dreammall-frontend",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#dreammall-frontend"},[e("span",null,"Dreammall Frontend")])],-1),h={href:"https://nodejs.org/",target:"_blank",rel:"noopener noreferrer"},u=e("img",{src:"https://img.shields.io/badge/nodejs->%3D20.5.0-blue",alt:"nodejs"},null,-1),m={href:"https://www.npmjs.com/package/npm",target:"_blank",rel:"noopener noreferrer"},g=e("img",{src:"https://img.shields.io/badge/npm-latest-blue",alt:"npm"},null,-1),b={href:"https://www.docker.com/",target:"_blank",rel:"noopener noreferrer"},v=e("img",{src:"https://img.shields.io/badge/docker-latest-blue",alt:"docker"},null,-1),f={href:"https://jqlang.github.io/jq/",target:"_blank",rel:"noopener noreferrer"},_=e("img",{src:"https://img.shields.io/badge/jq-latest-blue",alt:"jq"},null,-1),k={href:"https://vuejs.org/",target:"_blank",rel:"noopener noreferrer"},y=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.vue&label=vue&color=green",alt:"vue"},null,-1),F={href:"https://vike.dev/",target:"_blank",rel:"noopener noreferrer"},w=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.vike&label=vike&color=green",alt:"vike"},null,-1),x={href:"https://vuetifyjs.com/",target:"_blank",rel:"noopener noreferrer"},j=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.vuetify&label=vuetify&color=green",alt:"vuetify"},null,-1),T={href:"https://pinia.vuejs.org/",target:"_blank",rel:"noopener noreferrer"},C=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies.pinia&label=pinia&color=green",alt:"pinia"},null,-1),q={href:"https://vue-i18n.intlify.dev/",target:"_blank",rel:"noopener noreferrer"},R=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=dependencies['vue-i18n']&label=vue-i18n&color=green",alt:"vue-i18n"},null,-1),D={href:"https://eslint.org/",target:"_blank",rel:"noopener noreferrer"},I=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.eslint&label=eslint&color=yellow",alt:"eslint"},null,-1),A={href:"https://remark.js.org/",target:"_blank",rel:"noopener noreferrer"},E=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies['remark-cli']&label=remark-cli&color=yellow",alt:"remark-cli"},null,-1),S={href:"https://stylelint.io/",target:"_blank",rel:"noopener noreferrer"},B=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.stylelint&label=stylelint&color=yellow",alt:"stylelint"},null,-1),N={href:"https://vitest.dev/",target:"_blank",rel:"noopener noreferrer"},P=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.vitest&label=vitest&color=yellow",alt:"vitest"},null,-1),O={href:"https://storybook.js.org/",target:"_blank",rel:"noopener noreferrer"},H=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.storybook&label=storybook&color=orange",alt:"storybook"},null,-1),L={href:"https://vuepress.vuejs.org/",target:"_blank",rel:"noopener noreferrer"},z=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.vuepress&label=vuepress&color=orange",alt:"vuepress"},null,-1),K={href:"https://www.chromatic.com/",target:"_blank",rel:"noopener noreferrer"},M=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2FIT4Change%2Fboilerplate-frontend%2Fmaster%2Fpackage.json&query=devDependencies.chromatic&label=chromatic&color=orange",alt:"chromatic"},null,-1),U=s('The Dreammall frontend.
Requirements & Technology
To be able to build this project you need nodejs, npm and optional docker and jq.
The project uses vite as builder, vike to do the SSR. The design framework is vuetify which requires the frontend framework vue3. For localization vue-i18n is used; Session storage is handled with pinia.
Testing is done with vitest and code style is enforced with eslint, remark-cli and stylelint.
This projects utilizes storybook and chromatic to develop, document & test frontend components and vuepress for static documentation generation.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
npm run build | Compiles and minifies for production |
npm run server:prod | Runs productions server |
| Develop | |
npm run dev | Compiles and hot-reloads for development |
npm run server:dev | Run development server |
npm run server:prod:ts | Run production server without build (ts-node) |
npm run server:build | Build Server into an executable cjs file |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:eslint | Run linter eslint |
npm run test:lint:locales | Run linter locales |
npm run test:lint:remark | Run linter remark |
npm run test:lint:style | Run linter stylelint |
npm run test:unit | Run all unit tests and generate coverage report |
npm run test:unit:update | Run unit tests, coverage and update snapshots |
npm run test:unit:dev | Run all unit tests in watch mode |
npm test | Run all tests & linters |
| Storybook | |
npm run storybook | Run Storybook |
npm run storybook:build | Build static storybook |
npm run storybook:test | Run tests against all storybook stories |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Chromatic | |
npm run chromatic | Run Chromatic. See Chromatic section for details |
| Maintenance | |
npm run update | Check for updates |
Docker
Docker can be run in development mode utilizing docker-compose.overwrite.yml:
docker compose up
+Docker can be run in production mode:
docker compose -f docker-compose.yml up
+Chromatic
In order to use the chromatic workflow you need to provide a CHROMATIC_PROJECT_TOKEN in the repository secrets.
If you want to run chromatic from the command line you either have to provide this variable as well
export CHROMATIC_PROJECT_TOKEN=...
+npm run chromatic
+or you have to append it via parameter:
npm run chromatic -- --project-token=...
+Update
You can get a list of packes to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+Endpoints
The following endpoints are provided given the right command is executed or all three if docker compose is used:
How to use as part of a project
If you want to use this as part of a larger project, e.g. in conjunction with a backend also utilizing a boilerplate you cannot use the template mechanic provided by github for this repository.
You can use the following commands to include the whole git history of the boilerplate and be able to update according to changes to this repo using another remote.
git remote add xxx_boilerplate_frontend git@github.com:IT4Change/boilerplate-frontend.git
+git fetch xxx_boilerplate_frontend
+git merge -s ours --no-commit --allow-unrelated-histories xxx_boilerplate_frontend/master
+git read-tree --prefix=xxx/ -u xxx_boilerplate_frontend/master
+git commit -m "Imported boilerplate_frontend as a subtree under xxx/."
+To update the subtree you can use
git subtree pull -P xxx/ xxx_boilerplate_frontend master
+git commit -m "Updated boilerplate_frontend in subtree under xxx/."
+Where xxx refers to the folder and product part you want to use the boilerplate in. This assumes that you might need several copies of the frontend boilerplate for you product.
The Dreammall backend.
Requirements & Technology
To be able to build this project you need nodejs, npm and optional docker.
The project sets up an apollo server. It uses type-graphql.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
npm run build | Compiles and minifies for production |
npm run start | Runs productions server |
| Develop | |
npm run dev | Compiles and hot-reloads for development |
| Database | |
npm run db:migrate | Creates and executes migrations needed |
npm run db:reset | Drops Schema, run all migrations and seeds |
npm run db:seed | Run the seeds |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:eslint | Run linter eslint |
npm run test:lint:remark | Run linter remark |
npm run test:unit | Run all unit tests and generate coverage report |
npm test | Run all tests & linters |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Maintenance | |
npm run update | Check for updates |
Docker
Docker can be run in development mode utilizing docker-compose.overwrite.yml:
docker compose up
+Docker can be run in production mode:
docker compose -f docker-compose.yml up
+Update
You can get a list of packes to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+Endpoints
The following endpoints are provided given the right command is executed or all three if docker compose is used:
How to use as part of a project
If you want to use this as part of a larger project, e.g. in conjunction with a frontend also utilizing a boilerplate you cannot use the template mechanic provided by github for this repository.
You can use the following commands to include the whole git history of the boilerplate and be able to update according to changes to this repo using another remote.
git remote add xxx_boilerplate_backend git@github.com:IT4Change/boilerplate-backend.git
+git fetch xxx_boilerplate_backend
+git merge -s ours --no-commit --allow-unrelated-histories xxx_boilerplate_backend/master
+git read-tree --prefix=xxx/ -u xxx_boilerplate_backend/master
+git commit -m "Imported boilerplate_backend as a subtree under xxx/."
+To update the subtree you can use
git subtree pull -P xxx/ xxx_boilerplate_backend master
+git commit -m "Updated boilerplate_backend in subtree under xxx/."
+Where xxx refers to the folder and product part you want to use the boilerplate in. This assumes that you might need several copies of the frontend boilerplate for you product.
Database setup
The project is set up for a mysql database. Use
docker-compose up database
+in the main folder to run the database inside docker. You need to copy the .env.dist file to .env. Run npm run db:migrate to generate the database. It might be required to delete the migration folder beforehand.
Token validation
If you use the authentik database from the zip file, link the src/auth/public.pem to the main folder:
ln -s src/auth/public.pem public.pem
+Otherwise place the according certificate in the main folder with the name public.pem
License
`,10);function z(G,M){const t=o("ExternalLinkIcon");return d(),l("div",null,[p,e("p",null,[e("a",h,[u,a(t)]),e("a",m,[g,a(t)]),e("a",b,[k,a(t)]),e("a",v,[_,a(t)]),e("a",f,[x,a(t)]),e("a",F,[y,a(t)]),e("a",j,[w,a(t)]),e("a",q,[D,a(t)]),e("a",T,[R,a(t)]),e("a",A,[C,a(t)]),e("a",E,[I,a(t)])]),B,e("table",null,[L,e("tbody",null,[e("tr",null,[e("td",null,[e("a",N,[n("http://localhost:4000/graphql"),a(t)])]),P]),e("tr",null,[e("td",null,[e("a",S,[n("http://localhost:4000/playground"),a(t)])]),U])])]),H,e("p",null,[n("This mechanic was taken from this "),e("a",V,[n("source"),a(t)])]),Y])}const Q=r(c,[["render",z],["__file","index.html.vue"]]),J=JSON.parse('{"path":"/backend/","title":"Dreammall Backend","lang":"en-US","frontmatter":{},"headers":[{"level":2,"title":"Requirements & Technology","slug":"requirements-technology","link":"#requirements-technology","children":[]},{"level":2,"title":"Commands","slug":"commands","link":"#commands","children":[{"level":3,"title":"Docker","slug":"docker","link":"#docker","children":[]},{"level":3,"title":"Update","slug":"update","link":"#update","children":[]}]},{"level":2,"title":"Endpoints","slug":"endpoints","link":"#endpoints","children":[]},{"level":2,"title":"How to use as part of a project","slug":"how-to-use-as-part-of-a-project","link":"#how-to-use-as-part-of-a-project","children":[]},{"level":2,"title":"Database setup","slug":"database-setup","link":"#database-setup","children":[]},{"level":2,"title":"Token validation","slug":"token-validation","link":"#token-validation","children":[]},{"level":2,"title":"License","slug":"license","link":"#license","children":[]}],"git":{"updatedTime":1713376945000,"contributors":[{"name":"Hannes Heine","email":"heine.hannes@gmail.com","commits":1}]},"filePathRelative":"backend/README.md"}');export{Q as comp,J as data}; diff --git a/assets/index.html-BtvXRzQl.js b/assets/index.html-BtvXRzQl.js new file mode 100644 index 0000000000..782ab76dd0 --- /dev/null +++ b/assets/index.html-BtvXRzQl.js @@ -0,0 +1,15 @@ +import{_ as a}from"./dreammall-logo-BlW2bKby.js";import{_ as s,r as d,o as l,c as i,a as e,d as n,b as r,e as o}from"./app-DvhWSl6p.js";const c={},p=e("h1",{id:"dreammall-presenter",tabindex:"-1"},[e("a",{class:"header-anchor",href:"#dreammall-presenter"},[e("span",null,"Dreammall Presenter")])],-1),h={href:"https://nodejs.org/",target:"_blank",rel:"noopener noreferrer"},u=e("img",{src:"https://img.shields.io/badge/nodejs->%3D20.5.0-blue",alt:"nodejs"},null,-1),m={href:"https://www.npmjs.com/package/npm",target:"_blank",rel:"noopener noreferrer"},g=e("img",{src:"https://img.shields.io/badge/npm-latest-blue",alt:"npm"},null,-1),b={href:"https://www.docker.com/",target:"_blank",rel:"noopener noreferrer"},v=e("img",{src:"https://img.shields.io/badge/docker-latest-blue",alt:"docker"},null,-1),_={href:"https://jqlang.github.io/jq/",target:"_blank",rel:"noopener noreferrer"},f=e("img",{src:"https://img.shields.io/badge/jq-latest-blue",alt:"jq"},null,-1),k={href:"https://vuejs.org/",target:"_blank",rel:"noopener noreferrer"},y=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=dependencies.vue&label=vue&color=green",alt:"vue"},null,-1),F={href:"https://vike.dev/",target:"_blank",rel:"noopener noreferrer"},w=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=dependencies.vike&label=vike&color=green",alt:"vike"},null,-1),x={href:"https://vuetifyjs.com/",target:"_blank",rel:"noopener noreferrer"},j=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=dependencies.vuetify&label=vuetify&color=green",alt:"vuetify"},null,-1),q={href:"https://pinia.vuejs.org/",target:"_blank",rel:"noopener noreferrer"},R=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=dependencies.pinia&label=pinia&color=green",alt:"pinia"},null,-1),T={href:"https://vue-i18n.intlify.dev/",target:"_blank",rel:"noopener noreferrer"},D=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=dependencies['vue-i18n']&label=vue-i18n&color=green",alt:"vue-i18n"},null,-1),C={href:"https://eslint.org/",target:"_blank",rel:"noopener noreferrer"},A=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=devDependencies.eslint&label=eslint&color=yellow",alt:"eslint"},null,-1),E={href:"https://remark.js.org/",target:"_blank",rel:"noopener noreferrer"},S=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=devDependencies['remark-cli']&label=remark-cli&color=yellow",alt:"remark-cli"},null,-1),I={href:"https://stylelint.io/",target:"_blank",rel:"noopener noreferrer"},P=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=devDependencies.stylelint&label=stylelint&color=yellow",alt:"stylelint"},null,-1),B={href:"https://vitest.dev/",target:"_blank",rel:"noopener noreferrer"},N=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=devDependencies.vitest&label=vitest&color=yellow",alt:"vitest"},null,-1),O={href:"https://storybook.js.org/",target:"_blank",rel:"noopener noreferrer"},H=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=devDependencies.storybook&label=storybook&color=orange",alt:"storybook"},null,-1),L={href:"https://vuepress.vuejs.org/",target:"_blank",rel:"noopener noreferrer"},z=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=devDependencies.vuepress&label=vuepress&color=orange",alt:"vuepress"},null,-1),K={href:"https://www.chromatic.com/",target:"_blank",rel:"noopener noreferrer"},M=e("img",{src:"https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fpresenter%2Fpackage.json&query=devDependencies.chromatic&label=chromatic&color=orange",alt:"chromatic"},null,-1),U=o('The Dreammall presenter.
Requirements & Technology
To be able to build this project you need nodejs, npm and optional docker and jq.
The project uses vite as builder, vike to do the SSR. The design framework is vuetify which requires the frontend framework vue3. For localization vue-i18n is used; Session storage is handled with pinia.
Testing is done with vitest and code style is enforced with eslint, remark-cli and stylelint.
This projects utilizes storybook and chromatic to develop, document & test frontend components and vuepress for static documentation generation.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
npm run build | Compiles and minifies for production |
npm run server:prod | Runs productions server (node, cjs file) |
| Develop | |
npm run dev | Compiles and hot-reloads for development |
npm run server:dev | Run development server |
npm run server:prod:ts | Run production server without build (ts-node) |
npm run server:build | Build Server into an executable cjs file |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:eslint | Run linter eslint |
npm run test:lint:locales | Run linter locales |
npm run test:lint:remark | Run linter remark |
npm run test:lint:style | Run linter stylelint |
npm run test:unit | Run all unit tests and generate coverage report |
npm run test:unit:update | Run unit tests, coverage and update snapshots |
npm run test:unit:dev | Run all unit tests in watch mode |
npm test | Run all tests & linters |
| Storybook | |
npm run storybook | Run Storybook |
npm run storybook:build | Build static storybook |
npm run storybook:test | Run tests against all storybook stories |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Chromatic | |
npm run chromatic | Run Chromatic. See Chromatic section for details |
| Maintenance | |
npm run update | Check for updates |
Docker
Docker can be run in development mode utilizing docker-compose.overwrite.yml:
docker compose up
+Docker can be run in production mode:
docker compose -f docker-compose.yml up
+Chromatic
In order to use the chromatic workflow you need to provide a CHROMATIC_PROJECT_TOKEN in the repository secrets.
If you want to run chromatic from the command line you either have to provide this variable as well
export CHROMATIC_PROJECT_TOKEN=...
+npm run chromatic
+or you have to append it via parameter:
npm run chromatic -- --project-token=...
+Update
You can get a list of packes to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+Endpoints
The following endpoints are provided given the right command is executed or all three if docker compose is used:
How to use as part of a project
If you want to use this as part of a larger project, e.g. in conjunction with a backend also utilizing a boilerplate you cannot use the template mechanic provided by github for this repository.
You can use the following commands to include the whole git history of the boilerplate and be able to update according to changes to this repo using another remote.
git remote add xxx_boilerplate_frontend git@github.com:IT4Change/boilerplate-frontend.git
+git fetch xxx_boilerplate_frontend
+git merge -s ours --no-commit --allow-unrelated-histories xxx_boilerplate_frontend/master
+git read-tree --prefix=xxx/ -u xxx_boilerplate_frontend/master
+git commit -m "Imported boilerplate_frontend as a subtree under xxx/."
+To update the subtree you can use
git subtree pull -P xxx/ xxx_boilerplate_frontend master
+git commit -m "Updated boilerplate_frontend in subtree under xxx/."
+Where xxx refers to the folder and product part you want to use the boilerplate in. This assumes that you might need several copies of the frontend boilerplate for you product.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:remark | Run linter remark |
npm test | Run all tests & linters |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Release | |
npm run release | Propagate release version & generate changelog |
| Maintenance | |
npm run update | Check for updates |
Docker
The following endpoints are provided if docker compose is used:
How to release
Generate a new version using npm version --git-tag-version=false patch|minor|major. Then run npm run release to propagate the new version and generate the changelog
Update
You can get a list of packages to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+External Tools
This project is tested with Browserstack.
License
`,10);function X(Z,$){const n=a("ExternalLinkIcon"),l=a("RouteLink");return h(),i("div",null,[u,e("p",null,[e("a",m,[_,t(n)]),e("a",g,[f,t(n)]),e("a",k,[b,t(n)]),e("a",v,[x,t(n)])]),y,w,D,e("ul",null,[e("li",null,[t(l,{to:"/presenter/"},{default:r(()=>[o("Presenter")]),_:1})]),e("li",null,[t(l,{to:"/backend/"},{default:r(()=>[o("Backend")]),_:1})])]),F,e("p",null,[o("Deploy instructions can be found in "),t(l,{to:"/deplyoment/"},{default:r(()=>[o("deployment/")]),_:1})]),j,e("table",null,[E,e("tbody",null,[e("tr",null,[e("td",null,[e("a",L,[o("http://localhost:3306"),t(n)])]),B]),e("tr",null,[e("td",null,[e("a",P,[o("http://localhost:3000"),t(n)])]),R]),e("tr",null,[e("td",null,[e("a",T,[o("http://localhost:8081"),t(n)])]),C]),e("tr",null,[e("td",null,[e("a",S,[o("http://localhost:6006"),t(n)])]),A]),e("tr",null,[e("td",null,[e("a",N,[o("http://localhost:3001"),t(n)])]),M]),e("tr",null,[e("td",null,[e("a",q,[o("http://localhost:8082"),t(n)])]),H]),e("tr",null,[e("td",null,[e("a",I,[o("http://localhost:6007"),t(n)])]),V]),e("tr",null,[e("td",null,[e("a",G,[o("http://localhost:4000/graphql"),t(n)])]),Q]),e("tr",null,[e("td",null,[e("a",U,[o("http://localhost:4000/playground"),t(n)])]),Y]),e("tr",null,[e("td",null,[e("a",J,[o("http://localhost:8083"),t(n)])]),O]),e("tr",null,[e("td",null,[e("a",z,[o("http://localhost:8080"),t(n)])]),K])])]),W])}const ne=c(p,[["render",X],["__file","index.html.vue"]]),oe=JSON.parse('{"path":"/","title":"Dreammall.earth","lang":"en-US","frontmatter":{},"headers":[{"level":2,"title":"Modules","slug":"modules","link":"#modules","children":[]},{"level":2,"title":"Deploy","slug":"deploy","link":"#deploy","children":[]},{"level":2,"title":"Commands","slug":"commands","link":"#commands","children":[]},{"level":2,"title":"Docker","slug":"docker","link":"#docker","children":[]},{"level":2,"title":"How to release","slug":"how-to-release","link":"#how-to-release","children":[]},{"level":2,"title":"Update","slug":"update","link":"#update","children":[]},{"level":2,"title":"External Tools","slug":"external-tools","link":"#external-tools","children":[]},{"level":2,"title":"License","slug":"license","link":"#license","children":[]}],"git":{"updatedTime":1713376945000,"contributors":[{"name":"Hannes Heine","email":"heine.hannes@gmail.com","commits":1}]},"filePathRelative":"README.md"}');export{ne as comp,oe as data}; diff --git a/assets/index.html-YDzExJ6O.js b/assets/index.html-YDzExJ6O.js new file mode 100644 index 0000000000..59ba3097e8 --- /dev/null +++ b/assets/index.html-YDzExJ6O.js @@ -0,0 +1,66 @@ +import{_ as l,r as i,o,c as d,a as n,b as s,d as a,e as t}from"./app-DvhWSl6p.js";const c={},r=t(`Deployment
This document describes how to prepare a host to deploy from a specific branch and optionally to update when a push happens to that branch.
All instructions are for an Alpine 3.18 and require adjustment if a different system is used.
Update the system
apk update
+apk upgrade
+Install Software
Install nginx:
apk add nginx
+rc-update add nginx boot
+service nginx start
+Install node & npm:
apk add nodejs npm
+Install pm2:
npm install pm2 -g
+pm2 startup
+rc-update add pm2 boot
+Install git:
apk add git
+Install mariadb:
apk add mysql mysql-client
+service mariadb setup
+rc-update add mariadb boot
+# allow access from network
+vi /etc/my.cnf.d/mariadb-server.cnf
+# comment out \`skip-networking\`
+# add \`bind-address = localhost\`
+service mariadb start
+Install the project
Clone the repository:
cd /var/www/localhost/htdocs/
+git clone https://github.com/dreammall-earth/dreammall.earth.git
+cd dreammall.earth
+Configure nginx:
# replace nginx config
+cp -f deployment/nginx/default.conf /etc/nginx/http.d/default.conf
+# adjust the nginx config accordingly
+vi /etc/nginx/http.d/default.conf
+# frontend nginx config
+cp deployment/nginx/frontend.conf /etc/nginx/http.d/frontend.conf
+# adjust the frontend nginx config accordingly
+vi /etc/nginx/http.d/frontend.conf
+# note: replace log paths according to your installation directory
+service nginx restart
+Create Database User:
mysql
+CREATE USER 'dreammall'@'localhost' IDENTIFIED BY 'SECRET';
+GRANT ALL PRIVILEGES ON * . * TO 'dreammall'@'localhost';
+FLUSH PRIVILEGES;
+exit
+Configure database connection:
cp backend/.env.dist backend/.env
+# adjust the .env config as needed
+vi backend/.env
+# DATABASE_URL="mysql://dreammall:SECRET@localhost:3306/dreammall.earth"
+Configure backend connection:
cp presenter/.env.dist presenter/.env
+# adjust the .env config as needed
+vi presenter/.env
+# PUBLIC_ENV__ENDPOINTS__GRAPHQL_URI=http://localhost/api
+
+## Deploy the project
+
+To deploy the project run
+\`\`\`bash
+deployment/deploy.sh
+This will build all projects parts and start a pm2 instance to serve the corresponding services currently defined in the nginx config found in deployment/nginx/default.conf.
Those services are:
`,30),p=n("thead",null,[n("tr",null,[n("th",null,"Service"),n("th",null,"URL")])],-1),u=n("td",null,"presenter",-1),h={href:"https://host/",target:"_blank",rel:"noopener noreferrer"},m=n("td",null,"backend",-1),v={href:"https://host/api",target:"_blank",rel:"noopener noreferrer"},b=n("td",null,"docs",-1),k={href:"https://host/docs",target:"_blank",rel:"noopener noreferrer"},g=n("td",null,"webhooks (optional)",-1),f={href:"https://host/hooks/",target:"_blank",rel:"noopener noreferrer"},_=t(`(Optional) Webhook to auto update
To enable autoupdate from a github branch do the following:
Install webhook:
apk add webhook
+Configure webhook:
cp deployment/webhooks/hooks.json.template deployment/webhooks/hooks.json
+vi deployment/webhooks/hooks.json
+# adjust content of .github/webhooks/hooks.json
+# replace all variables accordingly
+
+# copy webhook service file
+cp deployment/init.d/webhook.template /etc/init.d/webhook
+vi /etc/init.d/webhook
+# adjust content of /etc/init.d/webhook
+chmod +x /etc/init.d/webhook
+
+# start the webhook service
+rc-update add webhook boot
+service webhook start
+In github configure a webhook pointing to the correct url with the following setting:
`,7),y=n("thead",null,[n("tr",null,[n("th",null,"Field"),n("th",null,"Value")])],-1),w=n("td",null,"Payload URL",-1),x={href:"https://host/hooks/github",target:"_blank",rel:"noopener noreferrer"},E=n("tr",null,[n("td",null,"Content type"),n("td",null,"application/json")],-1),j=n("tr",null,[n("td",null,"Secret"),n("td",null,"A SECRET")],-1),I=n("tr",null,[n("td",null,"SSL verification"),n("td",null,"Enable SSL verification")],-1),S=n("tr",null,[n("td",null,"Which events would you like to trigger this webhook?"),n("td",null,"Send me everything.")],-1),R=n("tr",null,[n("td",null,"Active"),n("td",null,"[x]")],-1),T=n("p",null,"Remark: Be aware that you need to restart webhook if you change the configuration in hooks.json e.g. when changing the branch to listen to.",-1);function L(C,A){const e=i("ExternalLinkIcon");return o(),d("div",null,[r,n("table",null,[p,n("tbody",null,[n("tr",null,[u,n("td",null,[n("a",h,[s("https://host/"),a(e)])])]),n("tr",null,[m,n("td",null,[n("a",v,[s("https://host/api"),a(e)])])]),n("tr",null,[b,n("td",null,[n("a",k,[s("https://host/docs"),a(e)])])]),n("tr",null,[g,n("td",null,[n("a",f,[s("https://host/hooks/"),a(e)])])])])]),_,n("table",null,[y,n("tbody",null,[n("tr",null,[w,n("td",null,[n("a",x,[s("https://host/hooks/github"),a(e)])])]),E,j,I,S,R])]),T])}const N=l(c,[["render",L],["__file","index.html.vue"]]),U=JSON.parse('{"path":"/deployment/","title":"Deployment","lang":"en-US","frontmatter":{},"headers":[{"level":2,"title":"Update the system","slug":"update-the-system","link":"#update-the-system","children":[]},{"level":2,"title":"Install Software","slug":"install-software","link":"#install-software","children":[]},{"level":2,"title":"Install the project","slug":"install-the-project","link":"#install-the-project","children":[]},{"level":2,"title":"(Optional) Webhook to auto update","slug":"optional-webhook-to-auto-update","link":"#optional-webhook-to-auto-update","children":[]}],"git":{"updatedTime":1713376945000,"contributors":[{"name":"Hannes Heine","email":"heine.hannes@gmail.com","commits":1}]},"filePathRelative":"deployment/README.md"}');export{N as comp,U as data}; diff --git a/assets/style-C3ozQjM4.css b/assets/style-C3ozQjM4.css new file mode 100644 index 0000000000..5ee0f6b4f3 --- /dev/null +++ b/assets/style-C3ozQjM4.css @@ -0,0 +1 @@ +.vp-back-to-top-button{position:fixed!important;bottom:4rem;inset-inline-end:1rem;z-index:100;width:48px;height:48px;padding:8px;border-width:0;border-radius:50%;background:var(--back-to-top-bg-color);color:var(--back-to-top-color);box-shadow:2px 2px 10px 4px var(--back-to-top-shadow);cursor:pointer}@media (max-width: 959px){.vp-back-to-top-button{transform:scale(.8);transform-origin:100% 100%}}@media print{.vp-back-to-top-button{display:none}}.vp-back-to-top-button:hover{color:var(--back-to-top-color-hover)}.vp-back-to-top-button .back-to-top-icon{overflow:hidden;width:100%;height:100%;background:currentcolor;border-radius:50%;-webkit-mask-image:var(--back-to-top-icon);mask-image:var(--back-to-top-icon);-webkit-mask-position:50%;mask-position:50%;-webkit-mask-size:cover;mask-size:cover}.vp-scroll-progress{position:absolute;right:-2px;bottom:-2px;width:52px;height:52px}.vp-scroll-progress svg{width:100%;height:100%}.vp-scroll-progress circle{opacity:.9;transform:rotate(-90deg);transform-origin:50% 50%}.back-to-top-enter-active,.back-to-top-leave-active{transition:opacity .3s}.back-to-top-enter-from,.back-to-top-leave-to{opacity:0}:root{--back-to-top-z-index: 5;--back-to-top-icon: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%201024%201024'%3e%3cpath%20d='M512%20843.2c-36.2%200-66.4-13.6-85.8-21.8-10.8-4.6-22.6%203.6-21.8%2015.2l7%20102c.4%206.2%207.6%209.4%2012.6%205.6l29-22c3.6-2.8%209-1.8%2011.4%202l41%2064.2c3%204.8%2010.2%204.8%2013.2%200l41-64.2c2.4-3.8%207.8-4.8%2011.4-2l29%2022c5%203.8%2012.2.6%2012.6-5.6l7-102c.8-11.6-11-20-21.8-15.2-19.6%208.2-49.6%2021.8-85.8%2021.8'/%3e%3cpath%20d='m795.4%20586.2-96-98.2C699.4%20172%20513%2032%20513%2032S324.8%20172%20324.8%20488l-96%2098.2c-3.6%203.6-5.2%209-4.4%2014.2L261.2%20824c1.8%2011.4%2014.2%2017%2023.6%2010.8L419%20744s41.4%2040%2094.2%2040%2092.2-40%2092.2-40l134.2%2090.8c9.2%206.2%2021.6.6%2023.6-10.8l37-223.8c.4-5.2-1.2-10.4-4.8-14M513%20384c-34%200-61.4-28.6-61.4-64s27.6-64%2061.4-64c34%200%2061.4%2028.6%2061.4%2064S547%20384%20513%20384'/%3e%3c/svg%3e");--back-to-top-bg-color: #fff;--back-to-top-color: #3eaf7c;--back-to-top-color-hover: #71cda3;--back-to-top-shadow: rgb(0 0 0 / 20%)}div[class*=language-]:hover:before{display:none}div[class*=language-]:hover .vp-copy-code-button{opacity:1}.vp-copy-code-button{position:absolute;top:.5em;right:.5em;z-index:5;width:2.5rem;height:2.5rem;padding:0;border-width:0;border-radius:.5rem;background:transparent;outline:none;opacity:0;cursor:pointer;transition:opacity .4s}@media print{.vp-copy-code-button{display:none}}.vp-copy-code-button:focus,.vp-copy-code-button.copied{opacity:1}.vp-copy-code-button:hover,.vp-copy-code-button.copied{background:var(--copy-code-hover)}.vp-copy-code-button.copied .vp-copy-icon{-webkit-mask-image:var(--code-copied-icon);mask-image:var(--code-copied-icon)}.vp-copy-code-button.copied:after{content:attr(data-copied);position:absolute;top:0;right:calc(100% + .25rem);display:block;height:1.25rem;padding:.625rem;border-radius:.5rem;background:var(--copy-code-hover);color:var(--copy-code-color);font-weight:500;line-height:1.25rem;white-space:nowrap}.vp-copy-icon{width:1.25rem;height:1.25rem;padding:.625rem;background:currentcolor;color:var(--copy-code-color);font-size:1.25rem;-webkit-mask-image:var(--code-copy-icon);mask-image:var(--code-copy-icon);-webkit-mask-position:50%;mask-position:50%;-webkit-mask-repeat:no-repeat;mask-repeat:no-repeat;-webkit-mask-size:1em;mask-size:1em}:root{--code-copy-icon: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2024%2024'%20fill='none'%20height='20'%20width='20'%20stroke='rgba(128,128,128,1)'%20stroke-width='2'%3e%3cpath%20stroke-linecap='round'%20stroke-linejoin='round'%20d='M9%205H7a2%202%200%200%200-2%202v12a2%202%200%200%200%202%202h10a2%202%200%200%200%202-2V7a2%202%200%200%200-2-2h-2M9%205a2%202%200%200%200%202%202h2a2%202%200%200%200%202-2M9%205a2%202%200%200%201%202-2h2a2%202%200%200%201%202%202'%20/%3e%3c/svg%3e");--code-copied-icon: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2024%2024'%20fill='none'%20height='20'%20width='20'%20stroke='rgba(128,128,128,1)'%20stroke-width='2'%3e%3cpath%20stroke-linecap='round'%20stroke-linejoin='round'%20d='M9%205H7a2%202%200%200%200-2%202v12a2%202%200%200%200%202%202h10a2%202%200%200%200%202-2V7a2%202%200%200%200-2-2h-2M9%205a2%202%200%200%200%202%202h2a2%202%200%200%200%202-2M9%205a2%202%200%200%201%202-2h2a2%202%200%200%201%202%202m-6%209%202%202%204-4'%20/%3e%3c/svg%3e");--copy-code-color: #9e9e9e;--copy-code-hover: rgb(0 0 0 / 50%)}:root{--external-link-icon-color: #aaa}.external-link-icon{position:relative;display:inline-block;color:var(--external-link-icon-color);vertical-align:middle;top:-1px}@media print{.external-link-icon{display:none}}.external-link-icon-sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border-width:0;-webkit-user-select:none;-moz-user-select:none;user-select:none}:root{--medium-zoom-z-index: 100;--medium-zoom-bg-color: #ffffff;--medium-zoom-opacity: 1}.medium-zoom-overlay{background-color:var(--medium-zoom-bg-color)!important;z-index:var(--medium-zoom-z-index)}.medium-zoom-overlay~img{z-index:calc(var(--medium-zoom-z-index) + 1)}.medium-zoom--opened .medium-zoom-overlay{opacity:var(--medium-zoom-opacity)}:root{--nprogress-color: #29d;--nprogress-z-index: 1031}#nprogress{pointer-events:none}#nprogress .bar{background:var(--nprogress-color);position:fixed;z-index:var(--nprogress-z-index);top:0;left:0;width:100%;height:2px}.vp-page-meta{max-width:var(--content-width);margin:0 auto;padding:.75rem 2.5rem;display:flex;flex-wrap:wrap;justify-content:space-between;overflow:auto}@media (max-width: 959px){.vp-page-meta{padding:2rem}}@media (max-width: 419px){.vp-page-meta{padding:1.5rem}}@media print{.vp-page-meta{margin:0!important;padding-inline:0!important}}@media (max-width: 719px){.vp-page-meta{display:block}}.vp-page-meta .vp-meta-item{flex-grow:1}.vp-page-meta .vp-meta-item .vp-meta-label{font-weight:500}.vp-page-meta .vp-meta-item .vp-meta-label:not(a){color:var(--c-text-lighter)}.vp-page-meta .vp-meta-item .vp-meta-info{color:var(--c-text-quote);font-weight:400}.vp-page-meta .git-info{text-align:end}.vp-page-meta .edit-link{margin-top:.25rem;margin-bottom:.25rem;margin-inline-end:.5rem;font-size:14px}@media print{.vp-page-meta .edit-link{display:none}}.vp-page-meta .edit-link .icon{position:relative;bottom:-.125em;width:1em;height:1em;margin-inline-end:.25em}.vp-page-meta .last-updated,.vp-page-meta .contributors{margin-top:.25rem;margin-bottom:.25rem;font-size:14px}@media (max-width: 719px){.vp-page-meta .last-updated,.vp-page-meta .contributors{font-size:13px;text-align:start}}.vp-page-nav{display:flex;flex-wrap:wrap;max-width:var(--content-width, 740px);min-height:2rem;margin-inline:auto;margin-top:0;padding-block:.5rem;padding-inline:2rem;border-top:1px solid var(--c-border);transition:border-top var(--t-color);padding-top:1rem;padding-bottom:0}@media (max-width: 959px){.vp-page-nav{padding-inline:1rem}}@media print{.vp-page-nav{display:none}}.vp-page-nav .route-link{display:inline-block;flex-grow:1;margin:.25rem;padding:.25rem .5rem;border:1px solid var(--c-border);border-radius:.25rem}.vp-page-nav .route-link:hover{background:var(--c-bg-light)}.vp-page-nav .route-link .hint{color:var(--c-text-quote);font-size:.875rem;line-height:2}.vp-page-nav .prev{text-align:start}.vp-page-nav .next{text-align:end}:root{--c-brand: #3eaf7c;--c-brand-light: #4abf8a;--c-bg: #ffffff;--c-bg-light: #f3f4f5;--c-bg-lighter: #eeeeee;--c-bg-dark: #ebebec;--c-bg-darker: #e6e6e6;--c-bg-navbar: var(--c-bg);--c-bg-sidebar: var(--c-bg);--c-bg-arrow: #cccccc;--c-text: #2c3e50;--c-text-accent: var(--c-brand);--c-text-light: #3a5169;--c-text-lighter: #4e6e8e;--c-text-lightest: #6a8bad;--c-text-quote: #999999;--c-border: #eaecef;--c-border-dark: #dfe2e5;--c-tip: #42b983;--c-tip-bg: var(--c-bg-light);--c-tip-title: var(--c-text);--c-tip-text: var(--c-text);--c-tip-text-accent: var(--c-text-accent);--c-warning: #ffc310;--c-warning-bg: #fffae3;--c-warning-bg-light: #fff3ba;--c-warning-bg-lighter: #fff0b0;--c-warning-border-dark: #f7dc91;--c-warning-details-bg: #fff5ca;--c-warning-title: #f1b300;--c-warning-text: #746000;--c-warning-text-accent: #edb100;--c-warning-text-light: #c1971c;--c-warning-text-quote: #ccab49;--c-danger: #f11e37;--c-danger-bg: #ffe0e0;--c-danger-bg-light: #ffcfde;--c-danger-bg-lighter: #ffc9c9;--c-danger-border-dark: #f1abab;--c-danger-details-bg: #ffd4d4;--c-danger-title: #ed1e2c;--c-danger-text: #660000;--c-danger-text-accent: #bd1a1a;--c-danger-text-light: #b5474d;--c-danger-text-quote: #c15b5b;--c-details-bg: #eeeeee;--c-badge-tip: var(--c-tip);--c-badge-warning: #ecc808;--c-badge-warning-text: var(--c-bg);--c-badge-danger: #dc2626;--c-badge-danger-text: var(--c-bg);--c-code-group-tab-title: rgba(255, 255, 255, .9);--c-code-group-tab-bg: var(--code-bg-color);--c-code-group-tab-outline: var(var(--c-code-group-tab-title));--c-code-group-tab-active-border: var(--c-brand);--t-color: .3s ease;--t-transform: .3s ease;--code-bg-color: #282c34;--code-hl-bg-color: rgba(0, 0, 0, .66);--code-ln-color: #9e9e9e;--code-ln-wrapper-width: 3.5rem;--font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;--font-family-code: Consolas, Monaco, "Andale Mono", "Ubuntu Mono", monospace;--navbar-height: 3.6rem;--navbar-padding-v: .7rem;--navbar-padding-h: 1.5rem;--sidebar-width: 20rem;--sidebar-width-mobile: calc(var(--sidebar-width) * .82);--content-width: 740px;--homepage-width: 960px}.vp-back-to-top-button{--back-to-top-color: var(--c-brand);--back-to-top-color-hover: var(--c-brand-light);--back-to-top-bg-color: var(--c-bg)}.vp-catalog-wrapper{--catalog-bg-color: var(--c-bg);--catalog-bg-secondary-color: var(--c-bg-dark);--catalog-border-color: var(--c-border);--catalog-active-color: var(--c-brand);--catalog-hover-color: var(--c-brand-light)}.waline-wrapper{--waline-bg-color: var(--c-bg);--waline-bg-color-light: var(--c-bg-light);--waline-text-color: var(--c-color);--waline-border: 1px solid var(--c-border);--waline-border-color: var(--c-border);--waline-theme-color: var(--c-brand);--waline-active-color: var(--c-brand-light)}.DocSearch{--docsearch-primary-color: var(--c-brand);--docsearch-text-color: var(--c-text);--docsearch-highlight-color: var(--c-brand);--docsearch-muted-color: var(--c-text-quote);--docsearch-container-background: rgba(9, 10, 17, .8);--docsearch-modal-background: var(--c-bg-light);--docsearch-searchbox-background: var(--c-bg-lighter);--docsearch-searchbox-focus-background: var(--c-bg);--docsearch-searchbox-shadow: inset 0 0 0 2px var(--c-brand);--docsearch-hit-color: var(--c-text-light);--docsearch-hit-active-color: var(--c-bg);--docsearch-hit-background: var(--c-bg);--docsearch-hit-shadow: 0 1px 3px 0 var(--c-border-dark);--docsearch-footer-background: var(--c-bg)}.external-link-icon{--external-link-icon-color: var(--c-text-quote)}.medium-zoom-overlay{--medium-zoom-bg-color: var(--c-bg)}#nprogress{--nprogress-color: var(--c-brand)}body{--photo-swipe-bullet: var(--c-bg);--photo-swipe-bullet-active: var(--c-brand)}body{--pwa-text-color: var(--c-text);--pwa-bg-color: var(--c-bg);--pwa-border-color: var(--c-brand);--pwa-btn-text-color: var(--c-bg);--pwa-btn-bg-color: var(--c-brand);--pwa-btn-hover-bg-color: var(--c-brand-light)}.language-modal-mask{--redirect-bg-color: var(--c-bg);--redirect-bg-color-light: var(--c-bg-light);--redirect-bg-color-lighter: var(--c-bg-lighter);--redirect-text-color: var(--c-text);--redirect-primary-color: var(--c-brand);--redirect-primary-hover-color: var(--c-brand-light);--redirect-primary-text-color: var(--c-bg)}.search-box{--search-bg-color: var(--c-bg);--search-accent-color: var(--c-brand);--search-text-color: var(--c-text);--search-border-color: var(--c-border);--search-item-text-color: var(--c-text-lighter);--search-item-focus-bg-color: var(--c-bg-light)}html.dark{--c-brand: #3aa675;--c-brand-light: #349469;--c-bg: #22272e;--c-bg-light: #2b313a;--c-bg-lighter: #262c34;--c-bg-dark: #343b44;--c-bg-darker: #37404c;--c-text: #adbac7;--c-text-light: #96a7b7;--c-text-lighter: #8b9eb0;--c-text-lightest: #8094a8;--c-border: #3e4c5a;--c-border-dark: #34404c;--c-tip: #318a62;--c-warning: #e0ad15;--c-warning-bg: #2d2f2d;--c-warning-bg-light: #423e2a;--c-warning-bg-lighter: #44442f;--c-warning-border-dark: #957c35;--c-warning-details-bg: #39392d;--c-warning-title: #fdca31;--c-warning-text: #d8d96d;--c-warning-text-accent: #ffbf00;--c-warning-text-light: #ddb84b;--c-warning-text-quote: #ccab49;--c-danger: #fc1e38;--c-danger-bg: #39232c;--c-danger-bg-light: #4b2b35;--c-danger-bg-lighter: #553040;--c-danger-border-dark: #a25151;--c-danger-details-bg: #482936;--c-danger-title: #fc2d3b;--c-danger-text: #ea9ca0;--c-danger-text-accent: #fd3636;--c-danger-text-light: #d9777c;--c-danger-text-quote: #d56b6b;--c-details-bg: #323843;--c-badge-warning: var(--c-warning);--c-badge-warning-text: #3c2e05;--c-badge-danger: var(--c-danger);--c-badge-danger-text: #401416;--code-hl-bg-color: #363b46}html.dark .DocSearch{--docsearch-logo-color: var(--c-text);--docsearch-modal-shadow: inset 1px 1px 0 0 #2c2e40, 0 3px 8px 0 #000309;--docsearch-key-shadow: inset 0 -2px 0 0 #282d55, inset 0 0 1px 1px #51577d, 0 2px 2px 0 rgba(3, 4, 9, .3);--docsearch-key-gradient: linear-gradient(-225deg, #444950, #1c1e21);--docsearch-footer-shadow: inset 0 1px 0 0 rgba(73, 76, 106, .5), 0 -4px 8px 0 rgba(0, 0, 0, .2)}html.dark body{--pwa-shadow-color: rgb(0 0 0 / 30%);--pwa-content-color: #ccc;--pwa-content-light-color: #999}html,body{padding:0;margin:0;background-color:var(--c-bg);transition:background-color var(--t-color)}html.dark{color-scheme:dark}html{font-size:16px}body{font-family:var(--font-family);-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;font-size:1rem;color:var(--c-text)}a{font-weight:500;color:var(--c-text-accent);text-decoration:none;overflow-wrap:break-word}p a code{font-weight:400;color:var(--c-text-accent)}kbd{font-family:var(--font-family-code);color:var(--c-text);background:var(--c-bg-lighter);border:solid .15rem var(--c-border-dark);border-bottom:solid .25rem var(--c-border-dark);border-radius:.15rem;padding:0 .15em}code{font-family:var(--font-family-code);color:var(--c-text-lighter);padding:.25rem .5rem;margin:0;font-size:.85em;background-color:var(--c-bg-light);border-radius:3px;overflow-wrap:break-word;transition:background-color var(--t-color)}blockquote{font-size:1rem;color:var(--c-text-quote);border-left:.2rem solid var(--c-border-dark);margin:1rem 0;padding:.25rem 0 .25rem 1rem;overflow-wrap:break-word}blockquote>p{margin:0}ul,ol{padding-left:1.2em}strong{font-weight:600}h1,h2,h3,h4,h5,h6{font-weight:600;line-height:1.25;overflow-wrap:break-word}h1:focus-visible,h2:focus-visible,h3:focus-visible,h4:focus-visible,h5:focus-visible,h6:focus-visible{outline:none}h1 .header-anchor,h2 .header-anchor,h3 .header-anchor,h4 .header-anchor,h5 .header-anchor,h6 .header-anchor{color:inherit;text-decoration:none;position:relative}h1 .header-anchor:hover:before,h2 .header-anchor:hover:before,h3 .header-anchor:hover:before,h4 .header-anchor:hover:before,h5 .header-anchor:hover:before,h6 .header-anchor:hover:before{font-size:.8em;content:"¶";position:absolute;left:-.75em;color:var(--c-brand)}h1 .header-anchor:focus-visible,h2 .header-anchor:focus-visible,h3 .header-anchor:focus-visible,h4 .header-anchor:focus-visible,h5 .header-anchor:focus-visible,h6 .header-anchor:focus-visible{outline:none}h1 .header-anchor:focus-visible:before,h2 .header-anchor:focus-visible:before,h3 .header-anchor:focus-visible:before,h4 .header-anchor:focus-visible:before,h5 .header-anchor:focus-visible:before,h6 .header-anchor:focus-visible:before{content:"¶";position:absolute;left:-.75em;color:var(--c-brand);outline:auto}h1{font-size:2.2rem}h2{font-size:1.65rem;padding-bottom:.3rem;border-bottom:1px solid var(--c-border);transition:border-color var(--t-color)}h3{font-size:1.35rem}h4{font-size:1.15rem}h5{font-size:1.05rem}h6{font-size:1rem}@media print{a[href^="http://"]:after,a[href^="https://"]:after{content:" (" attr(href) ") "}}p,ul,ol{line-height:1.7;overflow-wrap:break-word}hr{border:0;border-top:1px solid var(--c-border)}table{border-collapse:collapse;margin:1rem 0;display:block;overflow-x:auto;transition:border-color var(--t-color)}tr{border-top:1px solid var(--c-border-dark);transition:border-color var(--t-color)}tr:nth-child(2n){background-color:var(--c-bg-light);transition:background-color var(--t-color)}tr:nth-child(2n) code{background-color:var(--c-bg-dark)}th,td{padding:.6em 1em;border:1px solid var(--c-border-dark);transition:border-color var(--t-color)}.arrow{display:inline-block;vertical-align:middle;width:1em;height:1em;background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='rgba(0,0,0,0.5)' d='M7.41 15.41L12 10.83l4.59 4.58L18 14l-6-6-6 6z'/%3E%3C/svg%3E");background-position:center;background-repeat:no-repeat;line-height:normal;transition:all .3s}html.dark .arrow{background-image:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='rgba(255,255,255,0.5)' d='M7.41 15.41L12 10.83l4.59 4.58L18 14l-6-6-6 6z'/%3E%3C/svg%3E")}.arrow.down{transform:rotate(180deg)}.arrow.right{transform:rotate(90deg)}.arrow.left{transform:rotate(-90deg)}.badge{display:inline-block;font-size:14px;font-weight:600;height:18px;line-height:18px;border-radius:3px;padding:0 6px;color:var(--c-bg);vertical-align:top;transition:color var(--t-color),background-color var(--t-color)}.badge.tip{background-color:var(--c-badge-tip)}.badge.warning{background-color:var(--c-badge-warning);color:var(--c-badge-warning-text)}.badge.danger{background-color:var(--c-badge-danger);color:var(--c-badge-danger-text)}.badge+.badge{margin-left:5px}code[class*=language-],pre[class*=language-]{color:#ccc;background:none;font-family:var(--font-family-code);font-size:1em;text-align:left;white-space:pre;word-spacing:normal;word-break:normal;word-wrap:normal;line-height:1.5;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-hyphens:none;hyphens:none}pre[class*=language-]{padding:1em;margin:.5em 0;overflow:auto}:not(pre)>code[class*=language-],pre[class*=language-]{background:#2d2d2d}:not(pre)>code[class*=language-]{padding:.1em;border-radius:.3em;white-space:normal}.token.comment,.token.block-comment,.token.prolog,.token.doctype,.token.cdata{color:#999}.token.punctuation{color:#ccc}.token.tag,.token.attr-name,.token.namespace,.token.deleted{color:#ec5975}.token.function-name{color:#6196cc}.token.boolean,.token.number,.token.function{color:#f08d49}.token.property,.token.class-name,.token.constant,.token.symbol{color:#f8c555}.token.selector,.token.important,.token.atrule,.token.keyword,.token.builtin{color:#cc99cd}.token.string,.token.char,.token.attr-value,.token.regex,.token.variable{color:#7ec699}.token.operator,.token.entity,.token.url{color:#67cdcc}.token.important,.token.bold{font-weight:700}.token.italic{font-style:italic}.token.entity{cursor:help}.token.inserted{color:#3eaf7c}.theme-default-content pre,.theme-default-content pre[class*=language-]{line-height:1.375;padding:1.3rem 1.5rem;margin:.85rem 0;border-radius:6px;overflow:auto}.theme-default-content pre code,.theme-default-content pre[class*=language-] code{color:#fff;padding:0;background-color:transparent!important;border-radius:0;overflow-wrap:unset;-webkit-font-smoothing:auto;-moz-osx-font-smoothing:auto}.theme-default-content .line-number{font-family:var(--font-family-code)}div[class*=language-]{position:relative;background-color:var(--code-bg-color);border-radius:6px}div[class*=language-]:before{content:attr(data-title);position:absolute;z-index:3;top:.8em;right:1em;font-size:.75rem;color:var(--code-ln-color)}div[class*=language-] pre,div[class*=language-] pre[class*=language-]{background:transparent!important;position:relative;z-index:1}div[class*=language-] .highlight-lines{-webkit-user-select:none;-moz-user-select:none;user-select:none;padding-top:1.3rem;position:absolute;top:0;left:0;width:100%;line-height:1.375}div[class*=language-] .highlight-lines .highlight-line{background-color:var(--code-hl-bg-color)}div[class*=language-]:not(.line-numbers-mode) .line-numbers{display:none}div[class*=language-].line-numbers-mode .highlight-lines .highlight-line{position:relative}div[class*=language-].line-numbers-mode .highlight-lines .highlight-line:before{content:" ";position:absolute;z-index:2;left:0;top:0;display:block;width:var(--code-ln-wrapper-width);height:100%}div[class*=language-].line-numbers-mode pre{margin-left:var(--code-ln-wrapper-width);padding-left:1rem;vertical-align:middle}div[class*=language-].line-numbers-mode .line-numbers{position:absolute;top:0;width:var(--code-ln-wrapper-width);text-align:center;color:var(--code-ln-color);padding-top:1.25rem;line-height:1.375;counter-reset:line-number}div[class*=language-].line-numbers-mode .line-numbers .line-number{position:relative;z-index:3;-webkit-user-select:none;-moz-user-select:none;user-select:none;height:1.375em}div[class*=language-].line-numbers-mode .line-numbers .line-number:before{counter-increment:line-number;content:counter(line-number);font-size:.85em}div[class*=language-].line-numbers-mode:after{content:"";position:absolute;top:0;left:0;width:var(--code-ln-wrapper-width);height:100%;border-radius:6px 0 0 6px;border-right:1px solid var(--code-hl-bg-color)}@media (max-width: 419px){.theme-default-content div[class*=language-]{margin:.85rem -1.5rem;border-radius:0}}.code-group__nav{margin-top:.85rem;margin-bottom:calc(-1.7rem - 6px);padding-bottom:calc(1.7rem - 6px);padding-left:10px;padding-top:10px;border-top-left-radius:6px;border-top-right-radius:6px;background-color:var(--c-code-group-tab-bg)}.code-group__nav-tab{border:0;padding:5px;cursor:pointer;background-color:transparent;font-size:.85em;line-height:1.4;color:var(--c-code-group-tab-title);font-weight:600}.code-group__nav-tab:focus{outline:none}.code-group__nav-tab:focus-visible{outline:1px solid var(--c-code-group-tab-outline)}.code-group__nav-tab-active{border-bottom:var(--c-code-group-tab-active-border) 1px solid}@media (max-width: 419px){.code-group__nav{margin-left:-1.5rem;margin-right:-1.5rem;border-radius:0}}.code-group-item{display:none}.code-group-item__active{display:block}.code-group-item>pre{background-color:orange}.custom-container{transition:color var(--t-color),border-color var(--t-color),background-color var(--t-color)}.custom-container .custom-container-title{font-weight:600}.custom-container .custom-container-title:not(:only-child){margin-bottom:-.4rem}.custom-container.tip,.custom-container.warning,.custom-container.danger{padding:.1rem 1.5rem;border-left-width:.5rem;border-left-style:solid;margin:1rem 0}.custom-container.tip{border-color:var(--c-tip);background-color:var(--c-tip-bg);color:var(--c-tip-text)}.custom-container.tip .custom-container-title{color:var(--c-tip-title)}.custom-container.tip a{color:var(--c-tip-text-accent)}.custom-container.tip code{background-color:var(--c-bg-dark)}.custom-container.warning{border-color:var(--c-warning);background-color:var(--c-warning-bg);color:var(--c-warning-text)}.custom-container.warning .custom-container-title{color:var(--c-warning-title)}.custom-container.warning a{color:var(--c-warning-text-accent)}.custom-container.warning blockquote{border-left-color:var(--c-warning-border-dark);color:var(--c-warning-text-quote)}.custom-container.warning code{color:var(--c-warning-text-light);background-color:var(--c-warning-bg-light)}.custom-container.warning details{background-color:var(--c-warning-details-bg)}.custom-container.warning details code{background-color:var(--c-warning-bg-lighter)}.custom-container.warning .external-link-icon{--external-link-icon-color: var(--c-warning-text-quote)}.custom-container.danger{border-color:var(--c-danger);background-color:var(--c-danger-bg);color:var(--c-danger-text)}.custom-container.danger .custom-container-title{color:var(--c-danger-title)}.custom-container.danger a{color:var(--c-danger-text-accent)}.custom-container.danger blockquote{border-left-color:var(--c-danger-border-dark);color:var(--c-danger-text-quote)}.custom-container.danger code{color:var(--c-danger-text-light);background-color:var(--c-danger-bg-light)}.custom-container.danger details{background-color:var(--c-danger-details-bg)}.custom-container.danger details code{background-color:var(--c-danger-bg-lighter)}.custom-container.danger .external-link-icon{--external-link-icon-color: var(--c-danger-text-quote)}.custom-container.details{display:block;position:relative;border-radius:2px;margin:1.6em 0;padding:1.6em;background-color:var(--c-details-bg)}.custom-container.details code{background-color:var(--c-bg-darker)}.custom-container.details h4{margin-top:0}.custom-container.details figure:last-child,.custom-container.details p:last-child{margin-bottom:0;padding-bottom:0}.custom-container.details summary{outline:none;cursor:pointer}.home{padding:var(--navbar-height) 2rem 0;max-width:var(--homepage-width);margin:0 auto;display:block}.home .hero{text-align:center}.home .hero img{max-width:100%;max-height:280px;display:block;margin:3rem auto 1.5rem}.home .hero h1{font-size:3rem}.home .hero h1,.home .hero .description,.home .hero .actions{margin:1.8rem auto}.home .hero .actions{display:flex;flex-wrap:wrap;gap:1rem;justify-content:center}.home .hero .description{max-width:35rem;font-size:1.6rem;line-height:1.3;color:var(--c-text-lightest)}.home .hero .action-button{display:inline-block;font-size:1.2rem;padding:.8rem 1.6rem;border-width:2px;border-style:solid;border-radius:4px;transition:background-color var(--t-color);box-sizing:border-box}.home .hero .action-button.primary{color:var(--c-bg);background-color:var(--c-brand);border-color:var(--c-brand)}.home .hero .action-button.primary:hover{background-color:var(--c-brand-light)}.home .hero .action-button.secondary{color:var(--c-brand);background-color:var(--c-bg);border-color:var(--c-brand)}.home .hero .action-button.secondary:hover{color:var(--c-bg);background-color:var(--c-brand-light)}.home .features{border-top:1px solid var(--c-border);transition:border-color var(--t-color);padding:1.2rem 0;margin-top:2.5rem;display:flex;flex-wrap:wrap;align-items:flex-start;align-content:stretch;justify-content:space-between}.home .feature{flex-grow:1;flex-basis:30%;max-width:30%}.home .feature h2{font-size:1.4rem;font-weight:500;border-bottom:none;padding-bottom:0;color:var(--c-text-light)}.home .feature p{color:var(--c-text-lighter)}.home .theme-default-content{padding:0;margin:0}.home .footer{padding:2.5rem;border-top:1px solid var(--c-border);text-align:center;color:var(--c-text-lighter);transition:border-color var(--t-color)}@media (max-width: 719px){.home .features{flex-direction:column}.home .feature{max-width:100%;padding:0 2.5rem}}@media (max-width: 419px){.home{padding-left:1.5rem;padding-right:1.5rem}.home .hero img{max-height:210px;margin:2rem auto 1.2rem}.home .hero h1{font-size:2rem}.home .hero h1,.home .hero .description,.home .hero .actions{margin:1.2rem auto}.home .hero .description{font-size:1.2rem}.home .hero .action-button{font-size:1rem;padding:.6rem 1.2rem}.home .feature h2{font-size:1.25rem}}.page{padding-top:var(--navbar-height);padding-left:var(--sidebar-width)}.navbar{position:fixed;z-index:20;top:0;left:0;right:0;height:var(--navbar-height);box-sizing:border-box;border-bottom:1px solid var(--c-border);background-color:var(--c-bg-navbar);transition:background-color var(--t-color),border-color var(--t-color)}.sidebar{font-size:16px;width:var(--sidebar-width);position:fixed;z-index:10;margin:0;top:var(--navbar-height);left:0;bottom:0;box-sizing:border-box;border-right:1px solid var(--c-border);overflow-y:auto;scrollbar-width:thin;scrollbar-color:var(--c-brand) var(--c-border);background-color:var(--c-bg-sidebar);transition:transform var(--t-transform),background-color var(--t-color),border-color var(--t-color)}.sidebar::-webkit-scrollbar{width:7px}.sidebar::-webkit-scrollbar-track{background-color:var(--c-border)}.sidebar::-webkit-scrollbar-thumb{background-color:var(--c-brand)}.sidebar-mask{position:fixed;z-index:9;top:0;left:0;width:100vw;height:100vh;display:none}.theme-container.sidebar-open .sidebar-mask{display:block}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(1){transform:rotate(45deg) translate3d(5.5px,5.5px,0)}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(2){transform:scale3d(0,1,1)}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(3){transform:rotate(-45deg) translate3d(6px,-6px,0)}.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(1),.theme-container.sidebar-open .navbar>.toggle-sidebar-button .icon span:nth-child(3){transform-origin:center}.theme-container.no-navbar .theme-default-content h1,.theme-container.no-navbar .theme-default-content h2,.theme-container.no-navbar .theme-default-content h3,.theme-container.no-navbar .theme-default-content h4,.theme-container.no-navbar .theme-default-content h5,.theme-container.no-navbar .theme-default-content h6{margin-top:1.5rem;padding-top:0}.theme-container.no-navbar .page{padding-top:0}.theme-container.no-navbar .sidebar{top:0}.theme-container.no-sidebar .sidebar{display:none}@media (max-width: 719px){.theme-container.no-sidebar .sidebar{display:block}}.theme-container.no-sidebar .page{padding-left:0}.theme-default-content a:not(.header-anchor):hover{text-decoration:underline}.theme-default-content img{max-width:100%}.theme-default-content h1,.theme-default-content h2,.theme-default-content h3,.theme-default-content h4,.theme-default-content h5,.theme-default-content h6{margin-top:calc(.5rem - var(--navbar-height));padding-top:calc(1rem + var(--navbar-height));margin-bottom:0}.theme-default-content h1:first-child,.theme-default-content h2:first-child,.theme-default-content h3:first-child,.theme-default-content h4:first-child,.theme-default-content h5:first-child,.theme-default-content h6:first-child{margin-bottom:1rem}.theme-default-content h1:first-child+p,.theme-default-content h1:first-child+pre,.theme-default-content h1:first-child+.custom-container,.theme-default-content h2:first-child+p,.theme-default-content h2:first-child+pre,.theme-default-content h2:first-child+.custom-container,.theme-default-content h3:first-child+p,.theme-default-content h3:first-child+pre,.theme-default-content h3:first-child+.custom-container,.theme-default-content h4:first-child+p,.theme-default-content h4:first-child+pre,.theme-default-content h4:first-child+.custom-container,.theme-default-content h5:first-child+p,.theme-default-content h5:first-child+pre,.theme-default-content h5:first-child+.custom-container,.theme-default-content h6:first-child+p,.theme-default-content h6:first-child+pre,.theme-default-content h6:first-child+.custom-container{margin-top:2rem}@media (max-width: 959px){.sidebar{font-size:15px;width:var(--sidebar-width-mobile)}.page{padding-left:var(--sidebar-width-mobile)}}@media (max-width: 719px){.sidebar{top:0;padding-top:var(--navbar-height);transform:translate(-100%)}.page{padding-left:0}.theme-container.sidebar-open .sidebar{transform:translate(0)}.theme-container.no-navbar .sidebar{padding-top:0}}@media (max-width: 419px){h1{font-size:1.9rem}}#vp-comment{max-width:var(--content-width);margin:0 auto;padding:2rem 2.5rem}@media (max-width: 959px){#vp-comment{padding:2rem}}@media (max-width: 419px){#vp-comment{padding:1.5rem}}.navbar{--navbar-line-height: calc( var(--navbar-height) - 2 * var(--navbar-padding-v) );padding:var(--navbar-padding-v) var(--navbar-padding-h);line-height:var(--navbar-line-height)}.navbar .logo{height:var(--navbar-line-height);margin-right:var(--navbar-padding-v);vertical-align:top}.navbar .site-name{font-size:1.3rem;font-weight:600;color:var(--c-text);position:relative}.navbar .navbar-items-wrapper{display:flex;position:absolute;box-sizing:border-box;top:var(--navbar-padding-v);right:var(--navbar-padding-h);height:var(--navbar-line-height);padding-left:var(--navbar-padding-h);white-space:nowrap;font-size:.9rem}.navbar .navbar-items-wrapper .search-box{flex:0 0 auto;vertical-align:top}@media screen and (max-width: 719px){.navbar{padding-left:4rem}.navbar .site-name{display:block;width:calc(100vw - 11rem);overflow:hidden;white-space:nowrap;text-overflow:ellipsis}.navbar .can-hide{display:none}}.navbar-items{display:inline-block}@media print{.navbar-items{display:none}}.navbar-items a{display:inline-block;line-height:1.4rem;color:inherit}.navbar-items a:hover,.navbar-items a.route-link-active{color:var(--c-text)}.navbar-items .navbar-item{position:relative;display:inline-block;margin-left:1.5rem;line-height:var(--navbar-line-height)}.navbar-items .navbar-item:first-child{margin-left:0}.navbar-items .navbar-item>a:hover,.navbar-items .navbar-item>a.route-link-active{margin-bottom:-2px;border-bottom:2px solid var(--c-text-accent)}@media (max-width: 719px){.navbar-items .navbar-item{margin-left:0}.navbar-items .navbar-item>a:hover,.navbar-items .navbar-item>a.route-link-active{margin-bottom:0;border-bottom:none}.navbar-items a:hover,.navbar-items a.route-link-active{color:var(--c-text-accent)}}.toggle-sidebar-button{position:absolute;top:.6rem;left:1rem;display:none;padding:.6rem;cursor:pointer}.toggle-sidebar-button .icon{display:flex;flex-direction:column;justify-content:center;align-items:center;width:1.25rem;height:1.25rem;cursor:inherit}.toggle-sidebar-button .icon span{display:inline-block;width:100%;height:2px;border-radius:2px;background-color:var(--c-text);transition:transform var(--t-transform)}.toggle-sidebar-button .icon span:nth-child(2){margin:6px 0}@media screen and (max-width: 719px){.toggle-sidebar-button{display:block}}.toggle-color-mode-button{display:flex;margin:auto;margin-left:1rem;border:0;background:none;color:var(--c-text);opacity:.8;cursor:pointer}@media print{.toggle-color-mode-button{display:none}}.toggle-color-mode-button:hover{opacity:1}.toggle-color-mode-button .icon{width:1.25rem;height:1.25rem}.DocSearch{transition:background-color var(--t-color)}.navbar-dropdown-wrapper{cursor:pointer}.navbar-dropdown-wrapper .navbar-dropdown-title,.navbar-dropdown-wrapper .navbar-dropdown-title-mobile{display:block;font-size:.9rem;font-family:inherit;cursor:inherit;padding:inherit;line-height:1.4rem;background:transparent;border:none;font-weight:500;color:var(--c-text)}.navbar-dropdown-wrapper .navbar-dropdown-title:hover,.navbar-dropdown-wrapper .navbar-dropdown-title-mobile:hover{border-color:transparent}.navbar-dropdown-wrapper .navbar-dropdown-title .arrow,.navbar-dropdown-wrapper .navbar-dropdown-title-mobile .arrow{vertical-align:middle;margin-top:-1px;margin-left:.4rem}.navbar-dropdown-wrapper .navbar-dropdown-title-mobile{display:none;font-weight:600;font-size:inherit}.navbar-dropdown-wrapper .navbar-dropdown-title-mobile:hover{color:var(--c-text-accent)}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item{color:inherit;line-height:1.7rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle{margin:.45rem 0 0;border-top:1px solid var(--c-border);padding:1rem 0 .45rem;font-size:.9rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle>span{padding:0 1.5rem 0 1.25rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle>a{font-weight:inherit}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle>a.route-link-active:after{display:none}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subitem-wrapper{padding:0;list-style:none}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subitem-wrapper .navbar-dropdown-subitem{font-size:.9em}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a{display:block;line-height:1.7rem;position:relative;border-bottom:none;font-weight:400;margin-bottom:0;padding:0 1.5rem 0 1.25rem}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a:hover,.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a.route-link-active{color:var(--c-text-accent)}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a.route-link-active:after{content:"";width:0;height:0;border-left:5px solid var(--c-text-accent);border-top:3px solid transparent;border-bottom:3px solid transparent;position:absolute;top:calc(50% - 2px);left:9px}.navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item:first-child .navbar-dropdown-subtitle{margin-top:0;padding-top:0;border-top:0}.navbar-dropdown-wrapper.mobile.open .navbar-dropdown-title,.navbar-dropdown-wrapper.mobile.open .navbar-dropdown-title-mobile{margin-bottom:.5rem}.navbar-dropdown-wrapper.mobile .navbar-dropdown-title,.navbar-dropdown-wrapper.mobile .navbar-dropdown-title-mobile{display:none}.navbar-dropdown-wrapper.mobile .navbar-dropdown-title-mobile{display:block}.navbar-dropdown-wrapper.mobile .navbar-dropdown{transition:height .1s ease-out;overflow:hidden}.navbar-dropdown-wrapper.mobile .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle{border-top:0;margin-top:0;padding-top:0;padding-bottom:0}.navbar-dropdown-wrapper.mobile .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subtitle,.navbar-dropdown-wrapper.mobile .navbar-dropdown .navbar-dropdown-item>a{font-size:15px;line-height:2rem}.navbar-dropdown-wrapper.mobile .navbar-dropdown .navbar-dropdown-item .navbar-dropdown-subitem{font-size:14px;padding-left:1rem}.navbar-dropdown-wrapper:not(.mobile){height:1.8rem}.navbar-dropdown-wrapper:not(.mobile):hover .navbar-dropdown,.navbar-dropdown-wrapper:not(.mobile).open .navbar-dropdown{display:block!important}.navbar-dropdown-wrapper:not(.mobile).open:blur{display:none}.navbar-dropdown-wrapper:not(.mobile) .navbar-dropdown{display:none;height:auto!important;box-sizing:border-box;max-height:calc(100vh - 2.7rem);overflow-y:auto;position:absolute;top:100%;right:0;background-color:var(--c-bg-navbar);padding:.6rem 0;border:1px solid var(--c-border);border-bottom-color:var(--c-border-dark);text-align:left;border-radius:.25rem;white-space:nowrap;margin:0}.page{padding-bottom:2rem;display:block}.page .theme-default-content{max-width:var(--content-width);margin:0 auto;padding:2rem 2.5rem;padding-top:0}@media (max-width: 959px){.page .theme-default-content{padding:2rem}}@media (max-width: 419px){.page .theme-default-content{padding:1.5rem}}.sidebar ul{padding:0;margin:0;list-style-type:none}.sidebar a{display:inline-block}.sidebar .navbar-items{display:none;border-bottom:1px solid var(--c-border);transition:border-color var(--t-color);padding:.5rem 0 .75rem}.sidebar .navbar-items a{font-weight:600}.sidebar .navbar-items .navbar-item{display:block;line-height:1.25rem;font-size:1.1em;padding:.5rem 0 .5rem 1.5rem}.sidebar .sidebar-items{padding:1.5rem 0}@media (max-width: 719px){.sidebar .navbar-items{display:block}.sidebar .navbar-items .navbar-dropdown-wrapper .navbar-dropdown .navbar-dropdown-item a.route-link-active:after{top:calc(1rem - 2px)}.sidebar .sidebar-items{padding:1rem 0}}.sidebar-item{cursor:default;border-left:.25rem solid transparent;color:var(--c-text)}.sidebar-item:focus-visible{outline-width:1px;outline-offset:-1px}.sidebar-item.active:not(p.sidebar-heading){font-weight:600;color:var(--c-text-accent);border-left-color:var(--c-text-accent)}.sidebar-item.sidebar-heading{transition:color .15s ease;font-size:1.1em;font-weight:700;padding:.35rem 1.5rem .35rem 1.25rem;width:100%;box-sizing:border-box;margin:0}.sidebar-item.sidebar-heading+.sidebar-item-children{transition:height .1s ease-out;overflow:hidden;margin-bottom:.75rem}.sidebar-item.collapsible{cursor:pointer}.sidebar-item.collapsible .arrow{position:relative;top:-.12em;left:.5em}.sidebar-item:not(.sidebar-heading){font-size:1em;font-weight:400;display:inline-block;margin:0;padding:.35rem 1rem .35rem 2rem;line-height:1.4;width:100%;box-sizing:border-box}.sidebar-item:not(.sidebar-heading)+.sidebar-item-children{padding-left:1rem;font-size:.95em}.sidebar-item-children .sidebar-item-children .sidebar-item:not(.sidebar-heading){padding:.25rem 1rem .25rem 1.75rem}.sidebar-item-children .sidebar-item-children .sidebar-item:not(.sidebar-heading).active{font-weight:500;border-left-color:transparent}a.sidebar-heading+.sidebar-item-children .sidebar-item:not(.sidebar-heading).active{border-left-color:transparent}a.sidebar-item{cursor:pointer}a.sidebar-item:hover{color:var(--c-text-accent)}.table-of-contents .badge{vertical-align:middle}.dropdown-enter-from,.dropdown-leave-to{height:0!important}.fade-slide-y-enter-active{transition:all .2s ease}.fade-slide-y-leave-active{transition:all .2s cubic-bezier(1,.5,.8,1)}.fade-slide-y-enter-from,.fade-slide-y-leave-to{transform:translateY(10px);opacity:0} diff --git a/authentik/index.html b/authentik/index.html new file mode 100644 index 0000000000..80271f5d7c --- /dev/null +++ b/authentik/index.html @@ -0,0 +1,40 @@ + + + + + + + + +Authentik
This is an Authentik setup for development in order to make local testing for production behaviour as easy as possible including the authentication mechanisms.
Preperation
This package comes with an preconfigured authentic - which has its data mainly residing in a postgress database. The contents of this database is available in packed form.
To extract the database use:
./database.unpack.sh
+(Note: make sure the database is not running before executing this command)
Alternatively you can not extract the database, which will start the service with an empty database. Use the Docker Guide from Authentik to get you going then.
Start Docker
To start the authentik server and its services run:
docker compose up
+(Note: make sure to run this command in the authentik folder, since there is another docker-compose setup in the main folder)
User Credentials
You can navigate to the now running authentik by opening http://localhost:9000.
To login you can use the superadmins credentials:
| description | value |
|---|---|
| username | akadmin |
| admin@dreammall.earth | |
| password | dreammall |
Publish changes
If you want to publish changes to the database you can use the following command to pack the database:
./database.pack.sh
+(Note: this assumes you are not root and sets the permissions of the database files via sudo) (Note: make sure to shut down the database first before you run the script)
Dreammall Backend
![apollo-server](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fbackend%2Fpackage.json&query=dependencies["%40apollo%2Fserver"]&label=apollo-server&color=green){kind=icon}
![type-graphql](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdreammall-earth%2Fdreammall.earth%2Fmaster%2Fbackend%2Fpackage.json&query=dependencies["type-graphql"]&label=type-graphql&color=green){kind=icon}
The Dreammall backend.
Requirements & Technology
To be able to build this project you need nodejs, npm and optional docker.
The project sets up an apollo server. It uses type-graphql.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
npm run build | Compiles and minifies for production |
npm run start | Runs productions server |
| Develop | |
npm run dev | Compiles and hot-reloads for development |
| Database | |
npm run db:migrate | Creates and executes migrations needed |
npm run db:reset | Drops Schema, run all migrations and seeds |
npm run db:seed | Run the seeds |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:eslint | Run linter eslint |
npm run test:lint:remark | Run linter remark |
npm run test:unit | Run all unit tests and generate coverage report |
npm test | Run all tests & linters |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Maintenance | |
npm run update | Check for updates |
Docker
Docker can be run in development mode utilizing docker-compose.overwrite.yml:
docker compose up
+Docker can be run in production mode:
docker compose -f docker-compose.yml up
+Update
You can get a list of packes to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+Endpoints
The following endpoints are provided given the right command is executed or all three if docker compose is used:
| Endpoint | Description |
|---|---|
| http://localhost:4000/graphql | GraphQL API |
| http://localhost:4000/playground | GraphQL Playground |
How to use as part of a project
If you want to use this as part of a larger project, e.g. in conjunction with a frontend also utilizing a boilerplate you cannot use the template mechanic provided by github for this repository.
You can use the following commands to include the whole git history of the boilerplate and be able to update according to changes to this repo using another remote.
git remote add xxx_boilerplate_backend git@github.com:IT4Change/boilerplate-backend.git
+git fetch xxx_boilerplate_backend
+git merge -s ours --no-commit --allow-unrelated-histories xxx_boilerplate_backend/master
+git read-tree --prefix=xxx/ -u xxx_boilerplate_backend/master
+git commit -m "Imported boilerplate_backend as a subtree under xxx/."
+To update the subtree you can use
git subtree pull -P xxx/ xxx_boilerplate_backend master
+git commit -m "Updated boilerplate_backend in subtree under xxx/."
+Where xxx refers to the folder and product part you want to use the boilerplate in. This assumes that you might need several copies of the frontend boilerplate for you product.
This mechanic was taken from this source
Database setup
The project is set up for a mysql database. Use
docker-compose up database
+in the main folder to run the database inside docker. You need to copy the .env.dist file to .env. Run npm run db:migrate to generate the database. It might be required to delete the migration folder beforehand.
Token validation
If you use the authentik database from the zip file, link the src/auth/public.pem to the main folder:
ln -s src/auth/public.pem public.pem
+Otherwise place the according certificate in the main folder with the name public.pem
License
Deployment
This document describes how to prepare a host to deploy from a specific branch and optionally to update when a push happens to that branch.
All instructions are for an Alpine 3.18 and require adjustment if a different system is used.
Update the system
apk update
+apk upgrade
+Install Software
Install nginx:
apk add nginx
+rc-update add nginx boot
+service nginx start
+Install node & npm:
apk add nodejs npm
+Install pm2:
npm install pm2 -g
+pm2 startup
+rc-update add pm2 boot
+Install git:
apk add git
+Install mariadb:
apk add mysql mysql-client
+service mariadb setup
+rc-update add mariadb boot
+# allow access from network
+vi /etc/my.cnf.d/mariadb-server.cnf
+# comment out `skip-networking`
+# add `bind-address = localhost`
+service mariadb start
+Install the project
Clone the repository:
cd /var/www/localhost/htdocs/
+git clone https://github.com/dreammall-earth/dreammall.earth.git
+cd dreammall.earth
+Configure nginx:
# replace nginx config
+cp -f deployment/nginx/default.conf /etc/nginx/http.d/default.conf
+# adjust the nginx config accordingly
+vi /etc/nginx/http.d/default.conf
+# frontend nginx config
+cp deployment/nginx/frontend.conf /etc/nginx/http.d/frontend.conf
+# adjust the frontend nginx config accordingly
+vi /etc/nginx/http.d/frontend.conf
+# note: replace log paths according to your installation directory
+service nginx restart
+Create Database User:
mysql
+CREATE USER 'dreammall'@'localhost' IDENTIFIED BY 'SECRET';
+GRANT ALL PRIVILEGES ON * . * TO 'dreammall'@'localhost';
+FLUSH PRIVILEGES;
+exit
+Configure database connection:
cp backend/.env.dist backend/.env
+# adjust the .env config as needed
+vi backend/.env
+# DATABASE_URL="mysql://dreammall:SECRET@localhost:3306/dreammall.earth"
+Configure backend connection:
cp presenter/.env.dist presenter/.env
+# adjust the .env config as needed
+vi presenter/.env
+# PUBLIC_ENV__ENDPOINTS__GRAPHQL_URI=http://localhost/api
+
+## Deploy the project
+
+To deploy the project run
+```bash
+deployment/deploy.sh
+This will build all projects parts and start a pm2 instance to serve the corresponding services currently defined in the nginx config found in deployment/nginx/default.conf.
Those services are:
| Service | URL |
|---|---|
| presenter | https://host/ |
| backend | https://host/api |
| docs | https://host/docs |
| webhooks (optional) | https://host/hooks/ |
(Optional) Webhook to auto update
To enable autoupdate from a github branch do the following:
Install webhook:
apk add webhook
+Configure webhook:
cp deployment/webhooks/hooks.json.template deployment/webhooks/hooks.json
+vi deployment/webhooks/hooks.json
+# adjust content of .github/webhooks/hooks.json
+# replace all variables accordingly
+
+# copy webhook service file
+cp deployment/init.d/webhook.template /etc/init.d/webhook
+vi /etc/init.d/webhook
+# adjust content of /etc/init.d/webhook
+chmod +x /etc/init.d/webhook
+
+# start the webhook service
+rc-update add webhook boot
+service webhook start
+In github configure a webhook pointing to the correct url with the following setting:
| Field | Value |
|---|---|
| Payload URL | https://host/hooks/github |
| Content type | application/json |
| Secret | A SECRET |
| SSL verification | Enable SSL verification |
| Which events would you like to trigger this webhook? | Send me everything. |
| Active | [x] |
Remark: Be aware that you need to restart webhook if you change the configuration in hooks.json e.g. when changing the branch to listen to.
Dreammall Frontend
The Dreammall frontend.
Requirements & Technology
To be able to build this project you need nodejs, npm and optional docker and jq.
The project uses vite as builder, vike to do the SSR. The design framework is vuetify which requires the frontend framework vue3. For localization vue-i18n is used; Session storage is handled with pinia.
Testing is done with vitest and code style is enforced with eslint, remark-cli and stylelint.
This projects utilizes storybook and chromatic to develop, document & test frontend components and vuepress for static documentation generation.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
npm run build | Compiles and minifies for production |
npm run server:prod | Runs productions server |
| Develop | |
npm run dev | Compiles and hot-reloads for development |
npm run server:dev | Run development server |
npm run server:prod:ts | Run production server without build (ts-node) |
npm run server:build | Build Server into an executable cjs file |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:eslint | Run linter eslint |
npm run test:lint:locales | Run linter locales |
npm run test:lint:remark | Run linter remark |
npm run test:lint:style | Run linter stylelint |
npm run test:unit | Run all unit tests and generate coverage report |
npm run test:unit:update | Run unit tests, coverage and update snapshots |
npm run test:unit:dev | Run all unit tests in watch mode |
npm test | Run all tests & linters |
| Storybook | |
npm run storybook | Run Storybook |
npm run storybook:build | Build static storybook |
npm run storybook:test | Run tests against all storybook stories |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Chromatic | |
npm run chromatic | Run Chromatic. See Chromatic section for details |
| Maintenance | |
npm run update | Check for updates |
Docker
Docker can be run in development mode utilizing docker-compose.overwrite.yml:
docker compose up
+Docker can be run in production mode:
docker compose -f docker-compose.yml up
+Chromatic
In order to use the chromatic workflow you need to provide a CHROMATIC_PROJECT_TOKEN in the repository secrets.
If you want to run chromatic from the command line you either have to provide this variable as well
export CHROMATIC_PROJECT_TOKEN=...
+npm run chromatic
+or you have to append it via parameter:
npm run chromatic -- --project-token=...
+Update
You can get a list of packes to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+Endpoints
The following endpoints are provided given the right command is executed or all three if docker compose is used:
| Endpoint | Description |
|---|---|
| http://localhost:3000 | Web |
| http://localhost:6006 | Storybook |
| http://localhost:8080 | Documentation |
How to use as part of a project
If you want to use this as part of a larger project, e.g. in conjunction with a backend also utilizing a boilerplate you cannot use the template mechanic provided by github for this repository.
You can use the following commands to include the whole git history of the boilerplate and be able to update according to changes to this repo using another remote.
git remote add xxx_boilerplate_frontend git@github.com:IT4Change/boilerplate-frontend.git
+git fetch xxx_boilerplate_frontend
+git merge -s ours --no-commit --allow-unrelated-histories xxx_boilerplate_frontend/master
+git read-tree --prefix=xxx/ -u xxx_boilerplate_frontend/master
+git commit -m "Imported boilerplate_frontend as a subtree under xxx/."
+To update the subtree you can use
git subtree pull -P xxx/ xxx_boilerplate_frontend master
+git commit -m "Updated boilerplate_frontend in subtree under xxx/."
+Where xxx refers to the folder and product part you want to use the boilerplate in. This assumes that you might need several copies of the frontend boilerplate for you product.
This mechanic was taken from this source
Known Problems
- [ ] Image flicker
- [ ] Black Buttons
License
Dreammall.earth
Dreammall.earth websites & services
Modules
Deploy
Deploy instructions can be found in deployment/
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:remark | Run linter remark |
npm test | Run all tests & linters |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Release | |
npm run release | Propagate release version & generate changelog |
| Maintenance | |
npm run update | Check for updates |
Docker
The following endpoints are provided if docker compose is used:
| Endpoint | Description |
|---|---|
| http://localhost:3306 | MySQL Database |
| http://localhost:3000 | Presenter |
| http://localhost:8081 | Presenter Documentation |
| http://localhost:6006 | Presenter Storybook |
| http://localhost:3001 | Frontend |
| http://localhost:8082 | Frontend Documentation |
| http://localhost:6007 | Frontend Storybook |
| http://localhost:4000/graphql | Backend GraphQL API |
| http://localhost:4000/playground | Backend GraphQL Playground |
| http://localhost:8083 | Backend Documentation |
| http://localhost:8080 | Documentation |
How to release
Generate a new version using npm version --git-tag-version=false patch|minor|major. Then run npm run release to propagate the new version and generate the changelog
Update
You can get a list of packages to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+External Tools
This project is tested with Browserstack.
License
Dreammall Presenter
The Dreammall presenter.
Requirements & Technology
To be able to build this project you need nodejs, npm and optional docker and jq.
The project uses vite as builder, vike to do the SSR. The design framework is vuetify which requires the frontend framework vue3. For localization vue-i18n is used; Session storage is handled with pinia.
Testing is done with vitest and code style is enforced with eslint, remark-cli and stylelint.
This projects utilizes storybook and chromatic to develop, document & test frontend components and vuepress for static documentation generation.
Commands
The following commands are available:
| Command | Description |
|---|---|
npm install | Project setup |
npm run build | Compiles and minifies for production |
npm run server:prod | Runs productions server (node, cjs file) |
| Develop | |
npm run dev | Compiles and hot-reloads for development |
npm run server:dev | Run development server |
npm run server:prod:ts | Run production server without build (ts-node) |
npm run server:build | Build Server into an executable cjs file |
| Test | |
npm run test:lint | Run all linters |
npm run test:lint:eslint | Run linter eslint |
npm run test:lint:locales | Run linter locales |
npm run test:lint:remark | Run linter remark |
npm run test:lint:style | Run linter stylelint |
npm run test:unit | Run all unit tests and generate coverage report |
npm run test:unit:update | Run unit tests, coverage and update snapshots |
npm run test:unit:dev | Run all unit tests in watch mode |
npm test | Run all tests & linters |
| Storybook | |
npm run storybook | Run Storybook |
npm run storybook:build | Build static storybook |
npm run storybook:test | Run tests against all storybook stories |
| Documentation | |
npm run docs:dev | Run Documentation in development mode |
npm run docs:build | Build static documentation |
| Chromatic | |
npm run chromatic | Run Chromatic. See Chromatic section for details |
| Maintenance | |
npm run update | Check for updates |
Docker
Docker can be run in development mode utilizing docker-compose.overwrite.yml:
docker compose up
+Docker can be run in production mode:
docker compose -f docker-compose.yml up
+Chromatic
In order to use the chromatic workflow you need to provide a CHROMATIC_PROJECT_TOKEN in the repository secrets.
If you want to run chromatic from the command line you either have to provide this variable as well
export CHROMATIC_PROJECT_TOKEN=...
+npm run chromatic
+or you have to append it via parameter:
npm run chromatic -- --project-token=...
+Update
You can get a list of packes to update by running npm run update.
Appending -u will also update the packages in the package.json. You have to run npm install again after.
npm run update -- -u
+npm install
+Endpoints
The following endpoints are provided given the right command is executed or all three if docker compose is used:
| Endpoint | Description |
|---|---|
| http://localhost:3000 | Web |
| http://localhost:6006 | Storybook |
| http://localhost:8080 | Documentation |
How to use as part of a project
If you want to use this as part of a larger project, e.g. in conjunction with a backend also utilizing a boilerplate you cannot use the template mechanic provided by github for this repository.
You can use the following commands to include the whole git history of the boilerplate and be able to update according to changes to this repo using another remote.
git remote add xxx_boilerplate_frontend git@github.com:IT4Change/boilerplate-frontend.git
+git fetch xxx_boilerplate_frontend
+git merge -s ours --no-commit --allow-unrelated-histories xxx_boilerplate_frontend/master
+git read-tree --prefix=xxx/ -u xxx_boilerplate_frontend/master
+git commit -m "Imported boilerplate_frontend as a subtree under xxx/."
+To update the subtree you can use
git subtree pull -P xxx/ xxx_boilerplate_frontend master
+git commit -m "Updated boilerplate_frontend in subtree under xxx/."
+Where xxx refers to the folder and product part you want to use the boilerplate in. This assumes that you might need several copies of the frontend boilerplate for you product.
This mechanic was taken from this source
Known Problems
- [ ] Image flicker
- [ ] Black Buttons