From e9adc216e42290fca02af501e8d71b6a851fafd6 Mon Sep 17 00:00:00 2001 From: Yassine Doghri Date: Fri, 15 Apr 2022 09:47:48 +0000 Subject: [PATCH] docs: add Brazilian Portuguese and Norwegian Nynorsk languages --- docs/.vitepress/config.ts | 149 +++++- docs/src/.i18n-filter | 2 + docs/src/ar/contributing/_category_.json | 4 + docs/src/ar/contributing/guidelines.md | 154 +++++++ docs/src/ar/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/ar/getting-started/_category_.json | 4 + docs/src/br/contributing/_category_.json | 4 + docs/src/br/contributing/guidelines.md | 154 +++++++ docs/src/br/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/br/getting-started/_category_.json | 4 + docs/src/contributing/setup-development.md | 2 +- docs/src/de/contributing/_category_.json | 4 + docs/src/de/contributing/guidelines.md | 154 +++++++ docs/src/de/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/de/getting-started/_category_.json | 4 + docs/src/el/contributing/_category_.json | 4 + docs/src/el/contributing/guidelines.md | 154 +++++++ docs/src/el/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/el/getting-started/_category_.json | 4 + docs/src/es/contributing/_category_.json | 4 + docs/src/es/contributing/guidelines.md | 154 +++++++ docs/src/es/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/es/getting-started/_category_.json | 4 + docs/src/fr/contributing/_category_.json | 4 + docs/src/fr/contributing/guidelines.md | 154 +++++++ docs/src/fr/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/fr/getting-started/_category_.json | 4 + docs/src/getting-started/install.md | 2 +- docs/src/id/contributing/_category_.json | 4 + docs/src/id/contributing/guidelines.md | 154 +++++++ docs/src/id/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/id/getting-started/_category_.json | 4 + docs/src/it/contributing/_category_.json | 4 + docs/src/it/contributing/guidelines.md | 154 +++++++ docs/src/it/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/it/getting-started/_category_.json | 4 + docs/src/nl/contributing/_category_.json | 4 + docs/src/nl/contributing/guidelines.md | 154 +++++++ docs/src/nl/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/nl/getting-started/_category_.json | 4 + docs/src/nn-NO/contributing/_category_.json | 4 + docs/src/nn-NO/contributing/guidelines.md | 154 +++++++ .../nn-NO/contributing/setup-development.md | 423 ++++++++++++++++++ .../src/nn-NO/getting-started/_category_.json | 4 + docs/src/nn-NO/getting-started/install.md | 2 +- docs/src/nn-NO/index.md | 19 +- docs/src/oc/contributing/_category_.json | 4 + docs/src/oc/contributing/guidelines.md | 154 +++++++ docs/src/oc/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/oc/getting-started/_category_.json | 4 + docs/src/pl/contributing/_category_.json | 4 + docs/src/pl/contributing/guidelines.md | 154 +++++++ docs/src/pl/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/pl/getting-started/_category_.json | 4 + docs/src/pt-BR/contributing/_category_.json | 4 + docs/src/pt-BR/contributing/guidelines.md | 154 +++++++ .../pt-BR/contributing/setup-development.md | 423 ++++++++++++++++++ .../src/pt-BR/getting-started/_category_.json | 4 + docs/src/pt-BR/getting-started/install.md | 2 +- docs/src/pt-BR/index.md | 19 +- docs/src/pt/contributing/_category_.json | 4 + docs/src/pt/contributing/guidelines.md | 154 +++++++ docs/src/pt/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/pt/getting-started/_category_.json | 4 + docs/src/ru/contributing/_category_.json | 4 + docs/src/ru/contributing/guidelines.md | 154 +++++++ docs/src/ru/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/ru/getting-started/_category_.json | 4 + docs/src/sv/contributing/_category_.json | 4 + docs/src/sv/contributing/guidelines.md | 154 +++++++ docs/src/sv/contributing/setup-development.md | 423 ++++++++++++++++++ docs/src/sv/getting-started/_category_.json | 4 + 72 files changed, 9523 insertions(+), 34 deletions(-) create mode 100644 docs/src/ar/contributing/_category_.json create mode 100644 docs/src/ar/contributing/guidelines.md create mode 100644 docs/src/ar/contributing/setup-development.md create mode 100644 docs/src/ar/getting-started/_category_.json create mode 100644 docs/src/br/contributing/_category_.json create mode 100644 docs/src/br/contributing/guidelines.md create mode 100644 docs/src/br/contributing/setup-development.md create mode 100644 docs/src/br/getting-started/_category_.json create mode 100644 docs/src/de/contributing/_category_.json create mode 100644 docs/src/de/contributing/guidelines.md create mode 100644 docs/src/de/contributing/setup-development.md create mode 100644 docs/src/de/getting-started/_category_.json create mode 100644 docs/src/el/contributing/_category_.json create mode 100644 docs/src/el/contributing/guidelines.md create mode 100644 docs/src/el/contributing/setup-development.md create mode 100644 docs/src/el/getting-started/_category_.json create mode 100644 docs/src/es/contributing/_category_.json create mode 100644 docs/src/es/contributing/guidelines.md create mode 100644 docs/src/es/contributing/setup-development.md create mode 100644 docs/src/es/getting-started/_category_.json create mode 100644 docs/src/fr/contributing/_category_.json create mode 100644 docs/src/fr/contributing/guidelines.md create mode 100644 docs/src/fr/contributing/setup-development.md create mode 100644 docs/src/fr/getting-started/_category_.json create mode 100644 docs/src/id/contributing/_category_.json create mode 100644 docs/src/id/contributing/guidelines.md create mode 100644 docs/src/id/contributing/setup-development.md create mode 100644 docs/src/id/getting-started/_category_.json create mode 100644 docs/src/it/contributing/_category_.json create mode 100644 docs/src/it/contributing/guidelines.md create mode 100644 docs/src/it/contributing/setup-development.md create mode 100644 docs/src/it/getting-started/_category_.json create mode 100644 docs/src/nl/contributing/_category_.json create mode 100644 docs/src/nl/contributing/guidelines.md create mode 100644 docs/src/nl/contributing/setup-development.md create mode 100644 docs/src/nl/getting-started/_category_.json create mode 100644 docs/src/nn-NO/contributing/_category_.json create mode 100644 docs/src/nn-NO/contributing/guidelines.md create mode 100644 docs/src/nn-NO/contributing/setup-development.md create mode 100644 docs/src/nn-NO/getting-started/_category_.json create mode 100644 docs/src/oc/contributing/_category_.json create mode 100644 docs/src/oc/contributing/guidelines.md create mode 100644 docs/src/oc/contributing/setup-development.md create mode 100644 docs/src/oc/getting-started/_category_.json create mode 100644 docs/src/pl/contributing/_category_.json create mode 100644 docs/src/pl/contributing/guidelines.md create mode 100644 docs/src/pl/contributing/setup-development.md create mode 100644 docs/src/pl/getting-started/_category_.json create mode 100644 docs/src/pt-BR/contributing/_category_.json create mode 100644 docs/src/pt-BR/contributing/guidelines.md create mode 100644 docs/src/pt-BR/contributing/setup-development.md create mode 100644 docs/src/pt-BR/getting-started/_category_.json create mode 100644 docs/src/pt/contributing/_category_.json create mode 100644 docs/src/pt/contributing/guidelines.md create mode 100644 docs/src/pt/contributing/setup-development.md create mode 100644 docs/src/pt/getting-started/_category_.json create mode 100644 docs/src/ru/contributing/_category_.json create mode 100644 docs/src/ru/contributing/guidelines.md create mode 100644 docs/src/ru/contributing/setup-development.md create mode 100644 docs/src/ru/getting-started/_category_.json create mode 100644 docs/src/sv/contributing/_category_.json create mode 100644 docs/src/sv/contributing/guidelines.md create mode 100644 docs/src/sv/contributing/setup-development.md create mode 100644 docs/src/sv/getting-started/_category_.json diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 39a99798..d04c0702 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -1,9 +1,6 @@ import { defineConfig } from "vitepress"; export default defineConfig({ - title: "Castopod docs", - description: - "Check out the Castopod documentation! Install your own free & open-source podcast host, help make it better by contributing, or simply learn more about Castopod!", srcDir: "src", head: [ @@ -26,7 +23,7 @@ export default defineConfig({ { property: "og:image:alt", content: - "Castopod mascot waving hello and hoding a browser showcasing the Castopod documentation.", + "Castopod mascot waving hello and holding a browser showcasing the Castopod documentation.", }, ], ["meta", { property: "og:url", content: "https://docs.castopod.org/" }], @@ -43,6 +40,27 @@ export default defineConfig({ ], ], + locales: { + "/": { + lang: "en", + title: "Castopod documentation", + description: + "Check out the Castopod documentation! Install your own free & open-source podcast host, help make it better by contributing, or simply learn more about Castopod!", + }, + "/pt-BR/": { + lang: "pt-BR", + title: "Documentação de Castopod", + description: + "Castopod é uma plataforma de hospedagem de código livre & aberto feita para podcasters que querem se envolver e interagir com seu público.", + }, + "/nn-NO/": { + lang: "nn-NO", + title: "Castopod dokumentasjon", + description: + "Castopod er ei open og gratis løysing for dei som vil køyra si eiga podkasting-plattform, og for podkastarar som vil engasjera og samhandla med publikum.", + }, + }, + themeConfig: { logo: "/images/castopod-icon.svg", lastUpdated: "Last Updated", @@ -50,27 +68,74 @@ export default defineConfig({ docsDir: "docs/src", docsBranch: "develop", editLinks: true, - nav: [ - { - text: "Home", - link: "https://castopod.org/", + locales: { + "/": { + label: "English", + selectText: "Languages", + repoLabel: "Source", + nav: [ + { + text: "Home", + link: "https://castopod.org/", + }, + { + text: "Blog", + link: "https://blog.castopod.org/", + }, + { + text: "Github", + link: "https://github.com/ad-aures/castopod", + }, + ], + sidebar: { + "/": getGuideSidebarEn(), + }, }, - { - text: "Blog", - link: "https://blog.castopod.org/", + "/pt-BR/": { + label: "Português do Brasil", + selectText: "Línguas", + repoLabel: "Código fonte", + nav: [ + { + text: "Início", + link: "https://castopod.org/", + }, + { + text: "Blogue", + link: "https://blog.castopod.org/", + }, + { + text: "Github", + link: "https://github.com/ad-aures/castopod", + }, + ], + sidebar: { "/pt-BR/": getGuideSidebarPtBR() }, }, - { - text: "Github", - link: "https://github.com/ad-aures/castopod", + "/nn-NO/": { + label: "Norsk nynorsk", + selectText: "Språk", + repoLabel: "Kildekode", + nav: [ + { + text: "Heim", + link: "https://castopod.org/", + }, + { + text: "Blogg", + link: "https://blog.castopod.org/", + }, + { + text: "Github", + link: "https://github.com/ad-aures/castopod", + }, + ], + sidebar: { "/nn-NO/": getGuideSidebarNnNO() }, }, - ], - sidebar: { - "/": getGuideSidebar(), }, }, }); -function getGuideSidebar() { +function getGuideSidebarEn() { return [ { text: "Introduction", @@ -93,3 +158,51 @@ function getGuideSidebar() { }, ]; } + +function getGuideSidebarPtBR() { + return [ + { + text: "Introdução", + link: "/pt-BR/", + }, + { + text: "Começando", + children: [ + { text: "Instalar", link: "/pt-BR/getting-started/install" }, + { text: "Segurança", link: "/pt-BR/getting-started/security" }, + { text: "Atualizar", link: "/pt-BR/getting-started/update" }, + ], + }, + { + text: "Contributing", + children: [ + { text: "Guide", link: "/pt-BR/contributing/guidelines" }, + { text: "Dev Setup", link: "/pt-BR/contributing/setup-development" }, + ], + }, + ]; +} + +function getGuideSidebarNnNO() { + return [ + { + text: "Introduksjon", + link: "/nn-NO/", + }, + { + text: "Starter", + children: [ + { text: "Installer", link: "/nn-NO/getting-started/install" }, + { text: "Sikkerhet", link: "/nn-NO/getting-started/security" }, + { text: "Oppdaterer", link: "/nn-NO/getting-started/update" }, + ], + }, + { + text: "Contributing", + children: [ + { text: "Guide", link: "/nn-NO/contributing/guidelines" }, + { text: "Dev Setup", link: "/nn-NO/contributing/setup-development" }, + ], + }, + ]; +} diff --git a/docs/src/.i18n-filter b/docs/src/.i18n-filter index 25512c29..752d2440 100644 --- a/docs/src/.i18n-filter +++ b/docs/src/.i18n-filter @@ -2,3 +2,5 @@ public contributing getting-started index.md +pt-BR +nn-NO diff --git a/docs/src/ar/contributing/_category_.json b/docs/src/ar/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/ar/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/ar/contributing/guidelines.md b/docs/src/ar/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/ar/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/ar/contributing/setup-development.md b/docs/src/ar/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/ar/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/ar/getting-started/_category_.json b/docs/src/ar/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/ar/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/br/contributing/_category_.json b/docs/src/br/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/br/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/br/contributing/guidelines.md b/docs/src/br/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/br/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/br/contributing/setup-development.md b/docs/src/br/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/br/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/br/getting-started/_category_.json b/docs/src/br/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/br/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/contributing/setup-development.md b/docs/src/contributing/setup-development.md index b3c1df49..6aafb50b 100644 --- a/docs/src/contributing/setup-development.md +++ b/docs/src/contributing/setup-development.md @@ -245,7 +245,7 @@ You do not wish to use the VSCode devcontainer? No problem! ### Initialize and populate database -::: tip +::: tip Tip You may skip this section if you go through the install wizard (go to `/cp-install`). diff --git a/docs/src/de/contributing/_category_.json b/docs/src/de/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/de/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/de/contributing/guidelines.md b/docs/src/de/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/de/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/de/contributing/setup-development.md b/docs/src/de/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/de/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/de/getting-started/_category_.json b/docs/src/de/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/de/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/el/contributing/_category_.json b/docs/src/el/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/el/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/el/contributing/guidelines.md b/docs/src/el/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/el/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/el/contributing/setup-development.md b/docs/src/el/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/el/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/el/getting-started/_category_.json b/docs/src/el/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/el/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/es/contributing/_category_.json b/docs/src/es/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/es/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/es/contributing/guidelines.md b/docs/src/es/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/es/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/es/contributing/setup-development.md b/docs/src/es/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/es/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/es/getting-started/_category_.json b/docs/src/es/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/es/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/fr/contributing/_category_.json b/docs/src/fr/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/fr/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/fr/contributing/guidelines.md b/docs/src/fr/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/fr/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/fr/contributing/setup-development.md b/docs/src/fr/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/fr/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/fr/getting-started/_category_.json b/docs/src/fr/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/fr/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/getting-started/install.md b/docs/src/getting-started/install.md index 7d35b296..2c1cf904 100644 --- a/docs/src/getting-started/install.md +++ b/docs/src/getting-started/install.md @@ -35,7 +35,7 @@ Additionally, make sure that the following extensions are enabled in your PHP: > We recommend using [MariaDB](https://mariadb.org). -::: warning +::: warning Warning Castopod only works with supported MySQL 5.7 or higher compatible databases. It will break with the previous MySQL v5.6 for example as its end of life was on diff --git a/docs/src/id/contributing/_category_.json b/docs/src/id/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/id/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/id/contributing/guidelines.md b/docs/src/id/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/id/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/id/contributing/setup-development.md b/docs/src/id/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/id/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/id/getting-started/_category_.json b/docs/src/id/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/id/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/it/contributing/_category_.json b/docs/src/it/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/it/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/it/contributing/guidelines.md b/docs/src/it/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/it/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/it/contributing/setup-development.md b/docs/src/it/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/it/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/it/getting-started/_category_.json b/docs/src/it/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/it/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/nl/contributing/_category_.json b/docs/src/nl/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/nl/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/nl/contributing/guidelines.md b/docs/src/nl/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/nl/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/nl/contributing/setup-development.md b/docs/src/nl/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/nl/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/nl/getting-started/_category_.json b/docs/src/nl/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/nl/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/nn-NO/contributing/_category_.json b/docs/src/nn-NO/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/nn-NO/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/nn-NO/contributing/guidelines.md b/docs/src/nn-NO/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/nn-NO/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/nn-NO/contributing/setup-development.md b/docs/src/nn-NO/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/nn-NO/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/nn-NO/getting-started/_category_.json b/docs/src/nn-NO/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/nn-NO/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/nn-NO/getting-started/install.md b/docs/src/nn-NO/getting-started/install.md index fa6e5fa4..85991dcf 100644 --- a/docs/src/nn-NO/getting-started/install.md +++ b/docs/src/nn-NO/getting-started/install.md @@ -37,7 +37,7 @@ din: > Me tilrår [MariaDB](https://mariadb.org). -::: Åtvaring +::: warning Åtvaring Castopod verkar berre med databasar som støttar MySQL 5.7 eller nyare. MySQL 5.6 eller eldre vil ikkje fungera, ettersom den versjonen vart forelda i diff --git a/docs/src/nn-NO/index.md b/docs/src/nn-NO/index.md index c89a030f..8e16b9e0 100644 --- a/docs/src/nn-NO/index.md +++ b/docs/src/nn-NO/index.md @@ -199,17 +199,24 @@ lesa korleis du [GNU Affero General Public License v3.0](https://choosealicense.com/licenses/agpl-3.0/) -Copyright © 2020-d.d., [Ad Aures](https://adaures.com/). -https://img.shields.io/gitlab/v/release/2?color=brightgreen&gitlab_url=https%3A%2F%2Fcode.castopod.org%2F&include_prereleases&label=release -https://img.shields.io/github/license/ad-aures/castopod?color=blue -https://img.shields.io/badge/contributions-welcome-brightgreen.svg -https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg -https://img.shields.io/github/stars/ad-aures/castopod?style=social +Copyright © 2020-present, [Ad Aures](https://adaures.com/). [release]: https://code.castopod.org/adaures/castopod/-/releases +[release-badge]: + https://img.shields.io/gitlab/v/release/2?color=brightgreen&gitlab_url=https%3A%2F%2Fcode.castopod.org%2F&include_prereleases&label=release [license]: https://code.castopod.org/adaures/castopod/-/blob/beta/LICENSE.md +[license-badge]: + https://img.shields.io/github/license/ad-aures/castopod?color=blue [contributions]: https://code.castopod.org/adaures/castopod/-/issues +[contributions-badge]: + https://img.shields.io/badge/contributions-welcome-brightgreen.svg [semantic-release]: https://github.com/semantic-release/semantic-release +[semantic-release-badge]: + https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg [discord]: https://castopod.org/discord +[discord-badge]: https://img.shields.io/badge/chat-on%20discord-7389D8 [stars]: https://github.com/ad-aures/castopod/stargazers +[stars-badge]: + https://img.shields.io/github/stars/ad-aures/castopod?style=social [crowdin]: https://translate.castopod.org/project/castopod +[crowdin-badge]: https://badges.crowdin.net/castopod/localized.svg diff --git a/docs/src/oc/contributing/_category_.json b/docs/src/oc/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/oc/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/oc/contributing/guidelines.md b/docs/src/oc/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/oc/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/oc/contributing/setup-development.md b/docs/src/oc/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/oc/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/oc/getting-started/_category_.json b/docs/src/oc/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/oc/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/pl/contributing/_category_.json b/docs/src/pl/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/pl/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/pl/contributing/guidelines.md b/docs/src/pl/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/pl/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/pl/contributing/setup-development.md b/docs/src/pl/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/pl/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/pl/getting-started/_category_.json b/docs/src/pl/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/pl/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/pt-BR/contributing/_category_.json b/docs/src/pt-BR/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/pt-BR/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/pt-BR/contributing/guidelines.md b/docs/src/pt-BR/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/pt-BR/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/pt-BR/contributing/setup-development.md b/docs/src/pt-BR/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/pt-BR/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/pt-BR/getting-started/_category_.json b/docs/src/pt-BR/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/pt-BR/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/pt-BR/getting-started/install.md b/docs/src/pt-BR/getting-started/install.md index 0edbbb39..85c178f5 100644 --- a/docs/src/pt-BR/getting-started/install.md +++ b/docs/src/pt-BR/getting-started/install.md @@ -37,7 +37,7 @@ seu PHP: > Recomendamos usar o [MariaDB](https://mariadb.org). -::: aviso +::: warning Aviso Castopod só funciona com bancos de dados compatíveis com MySQL 5.7 ou superior. Vai quebrar com a versão anteiror do MySQL, v5.6, por exemplo, pois teve seu diff --git a/docs/src/pt-BR/index.md b/docs/src/pt-BR/index.md index a3591bd8..a3768236 100644 --- a/docs/src/pt-BR/index.md +++ b/docs/src/pt-BR/index.md @@ -203,17 +203,24 @@ patrocinadores. Se você quiser ajudar, por favor considere [Licença Pública Geral GNU Affero v3.0](https://choosealicense.com/licenses/agpl-3.0/) -Copyright © 2020-presente, [Ad Aures](https://adaures.com/). -https://img.shields.io/gitlab/v/release/2?color=brightgreen&gitlab_url=https%3A%2F%2Fcode.castopod.org%2F&include_prereleases&label=release -https://img.shields.io/github/license/ad-aures/castopod?color=blue -https://img.shields.io/badge/contributions-welcome-brightgreen.svg -https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg -https://img.shields.io/github/stars/ad-aures/castopod?style=social +Copyright © 2020-present, [Ad Aures](https://adaures.com/). [release]: https://code.castopod.org/adaures/castopod/-/releases +[release-badge]: + https://img.shields.io/gitlab/v/release/2?color=brightgreen&gitlab_url=https%3A%2F%2Fcode.castopod.org%2F&include_prereleases&label=release [license]: https://code.castopod.org/adaures/castopod/-/blob/beta/LICENSE.md +[license-badge]: + https://img.shields.io/github/license/ad-aures/castopod?color=blue [contributions]: https://code.castopod.org/adaures/castopod/-/issues +[contributions-badge]: + https://img.shields.io/badge/contributions-welcome-brightgreen.svg [semantic-release]: https://github.com/semantic-release/semantic-release +[semantic-release-badge]: + https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg [discord]: https://castopod.org/discord +[discord-badge]: https://img.shields.io/badge/chat-on%20discord-7389D8 [stars]: https://github.com/ad-aures/castopod/stargazers +[stars-badge]: + https://img.shields.io/github/stars/ad-aures/castopod?style=social [crowdin]: https://translate.castopod.org/project/castopod +[crowdin-badge]: https://badges.crowdin.net/castopod/localized.svg diff --git a/docs/src/pt/contributing/_category_.json b/docs/src/pt/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/pt/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/pt/contributing/guidelines.md b/docs/src/pt/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/pt/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/pt/contributing/setup-development.md b/docs/src/pt/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/pt/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/pt/getting-started/_category_.json b/docs/src/pt/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/pt/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/ru/contributing/_category_.json b/docs/src/ru/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/ru/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/ru/contributing/guidelines.md b/docs/src/ru/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/ru/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/ru/contributing/setup-development.md b/docs/src/ru/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/ru/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/ru/getting-started/_category_.json b/docs/src/ru/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/ru/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +} diff --git a/docs/src/sv/contributing/_category_.json b/docs/src/sv/contributing/_category_.json new file mode 100644 index 00000000..e12f1ce5 --- /dev/null +++ b/docs/src/sv/contributing/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Contributing", + "position": 3 +} diff --git a/docs/src/sv/contributing/guidelines.md b/docs/src/sv/contributing/guidelines.md new file mode 100644 index 00000000..1a53c89e --- /dev/null +++ b/docs/src/sv/contributing/guidelines.md @@ -0,0 +1,154 @@ +--- +title: Guidelines +--- + +# Contributing to Castopod + +Love Castopod and want to help? Thanks so much, there's something to do for +everybody! + +Please take a moment to review this document in order to make the contribution +process easy and effective for everyone involved. + +Following these guidelines helps to communicate that you respect the time of the +developers managing and developing this open source project. In return, they +should reciprocate that respect in addressing your issue or assessing patches +and features. + +::: info Note + +**Any** contribution made on a repository other than +[the original repository](https://code.castopod.org/adaures/castopod) will not +be accepted. + +::: + +## Using the issue tracker + +The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the +preferred channel for [bug reports](#bug-reports), +[features requests](#feature-requests) and +[submitting pull requests](#pull-requests). + +## ⚠️ Security issues and vulnerabilities + +If you encounter any security issue or vulnerability in the Castopod source, +please contact us directly by email at +[security@castopod.org](mailto:security@castopod.org) + +## Bug reports + +A bug is a _demonstrable problem_ that is caused by the code in the repository. +Good bug reports are extremely helpful - thank you! + +Guidelines for bug reports: + +1. **Use the issue search** — check if the issue has already been + reported. + +2. **Check if the issue has been fixed** — try to reproduce it using the + latest `main` branch in the repository. + +3. **Isolate the problem** — ideally create a + [reduced test case](https://css-tricks.com/reduced-test-cases/) and a live + example. + +A good bug report shouldn't leave others needing to chase you up for more +information. Please try to be as detailed as possible in your report. What is +your environment? What steps will reproduce the issue? What browser(s) and OS +experience the problem? What would you expect to be the outcome? All these +details will help people to fix any potential bugs. + +> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates) +> have been created for this project. You may use them to help you follow those +> guidelines. + +## Feature requests + +Feature requests are welcome. But take a moment to find out whether your idea +fits with the scope and aims of the project. It's up to _you_ to make a strong +case to convince the project's developers of the merits of this feature. Please +provide as much detail and context as possible. + +## Pull requests + +Good pull requests - patches, improvements, new features - are a fantastic help. +They should remain focused in scope and avoid containing unrelated commits. + +**Please ask first** before embarking on any significant pull request (e.g. +implementing features, refactoring code, porting to a different language), +otherwise you risk spending a lot of time working on something that the +project's developers might not want to merge into the project. + +Please adhere to the coding conventions used throughout a project (indentation, +accurate comments, etc.) and any other requirements (such as test coverage). + +Adhering to the following process is the best way to get your work included in +the project: + +1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the + project, clone your fork, and configure the remotes: + +```bash +# Clone your fork of the repo into the current directory +git clone https://code.castopod.org//castopod.git + +# Navigate to the newly cloned directory +cd castopod + +# Assign the original repo to a remote called "upstream" +git remote add upstream https://code.castopod.org/adaures/castopod.git +``` + +2. If you cloned a while ago, get the latest changes from upstream: + +```bash +git checkout main +git pull upstream main +``` + +3. Create a new topic branch (off the `main` branch) to contain your feature, + change, or fix: + +```bash +git checkout -b +``` + +4. Commit your changes in logical chunks. Please adhere to these + [git commit message guidelines](https://conventionalcommits.org/) or your + code is unlikely be merged into the main project. Use Git's + [interactive rebase](https://help.github.com/articles/about-git-rebase/) + feature to tidy up your commits before making them public. + +5. Locally merge (or rebase) the upstream dev branch into your topic branch: + +```bash +git pull [--rebase] upstream main +``` + +6. Push your topic branch up to your fork: + +```bash +git push origin +``` + +7. [Open a Pull Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html#new-merge-request-from-a-fork) + with a clear title and description. + +**IMPORTANT**: By submitting a patch, you agree to allow the project owners to +license your work under the terms of the +[GNU AGPLv3](https://code.castopod.org/adaures/castopod/-/blob/main/LICENSE). + +## Collaborating guidelines + +There are few basic rules to ensure high quality of the project: + +- Before merging, a PR requires at least two approvals from the collaborators + unless it's an architectural change, a large feature, etc. If it is, then at + least 50% of the core team have to agree to merge it, with every team member + having a full veto right. (i.e. every single one can block any PR) +- A PR should remain open for at least two days before merging (does not apply + for trivial contributions like fixing a typo). This way everyone has enough + time to look into it. + +You are always welcome to discuss and propose improvements to this guideline. diff --git a/docs/src/sv/contributing/setup-development.md b/docs/src/sv/contributing/setup-development.md new file mode 100644 index 00000000..6aafb50b --- /dev/null +++ b/docs/src/sv/contributing/setup-development.md @@ -0,0 +1,423 @@ +--- +title: Development setup +sidebarDepth: 3 +--- + +# Setup your development environment + +## Introduction + +Castopod is a web app based on the `php` framework +[CodeIgniter 4](https://codeigniter.com). + +We use [Docker](https://www.docker.com/) quickly setup a dev environment. A +`docker-compose.yml` and `Dockerfile` are included in the project's root folder +to help you kickstart your contribution. + +> You don't need any prior knowledge of Docker to follow the next steps. +> However, if you wish to use your own environment, feel free to do so! + +## Setup instructions + +### 1. Pre-requisites + +0. Install [docker](https://docs.docker.com/get-docker). + +1. Clone Castopod project by running: + + ```bash + git clone https://code.castopod.org/adaures/castopod.git + ``` + +2. Create a `.env` file with the minimum required config to connect the app to + the database and use redis as a cache handler: + + ```ini + CI_ENVIRONMENT="development" + # If set to development, you must run `npm run dev` to start the static assets server + vite.environment="development" + + # By default, this is set to true in the app config. + # For development, this must be set to false as it is + # on a local environment + app.forceGlobalSecureRequests=false + + app.baseURL="http://localhost:8080/" + app.mediaBaseURL="http://localhost:8080/" + + admin.gateway="cp-admin" + auth.gateway="cp-auth" + + database.default.hostname="mariadb" + database.default.database="castopod" + database.default.username="castopod" + database.default.password="castopod" + + cache.handler="redis" + cache.redis.host = "redis" + + # You may not want to use redis as your cache handler + # Comment/remove the two lines above and uncomment + # the next line for file caching. + #cache.handler="file" + ``` + + > _NB._ You can tweak your environment by setting more environment variables + > in your custom `.env` file. See the `env` for examples or the + > [CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) + > for more info. + +3. (for docker desktop) Add the repository you've cloned to docker desktop's + `Settings` > `Resources` > `File Sharing` + +### 2. (recommended) Develop inside the app Container with VSCode + +If you're working in VSCode, you can take advantage of the `.devcontainer/` +folder. It defines a development environment (dev container) with preinstalled +requirements and VSCode extensions so you don't have to worry about them. All +required services will be loaded automagically! 🪄 + +1. Install the VSCode extension + [Remote - Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) +2. `Ctrl/Cmd + Shift + P` > `Open in container` + + > The VSCode window will reload inside the dev container. Expect several + > minutes during first load as it is building all necessary services. + + **Note**: The dev container will start by running Castopod's php server. + During development, you will have to start [Vite](https://vitejs.dev)'s dev + server for compiling the typescript code and styles: + + ```bash + # run Vite dev server + npm run dev + ``` + + If there is any issue with the php server not running, you can restart them + using the following commands: + + ```bash + # run Castopod server + php spark serve - 0.0.0.0 + ``` + +3. You're all set! 🎉 + + You're now **inside the dev container**, you may use the VSCode console + (`Terminal` > `New Terminal`) to run any command: + + ```bash + # PHP is installed + php -v + + # Composer is installed + composer -V + + # npm is installed + npm -v + + # git is installed + git version + ``` + +For more info, see +[VSCode Remote Containers](https://code.visualstudio.com/docs/remote/containers) + +### 3. Start hacking + +You're all set! Start working your magic by updating the project's files! Help +yourself to the +[CodeIgniter4 User Guide](https://codeigniter.com/user_guide/index.html) for +more insights. + +To see your changes, go to: + +- `http://localhost:8080/` for the Castopod app +- `http://localhost:8888/` for the phpmyadmin interface: + + - username: **castopod** + - password: **castopod** + +### 2-alt. Develop outside the app container + +You do not wish to use the VSCode devcontainer? No problem! + +1. Start docker containers manually: + + Go to project's root folder and run: + + ```bash + # starts all services declared in docker-compose.yml file + # -d option starts the containers in the background + docker-compose up -d + + # See all running processes (you should see 3 processes running) + docker-compose ps + + # Alternatively, you can check all docker processes + docker ps -a + + ``` + + > The `docker-compose up -d` command will boot 4 containers in the + > background: + > + > - `castopod_app`: a php based container with Castopod requirements + > installed + > - `castopod_redis`: a [redis](https://redis.io/) database to handle queries + > and pages caching + > - `castopod_mariadb`: a [mariadb](https://mariadb.org/) server for + > persistent data + > - `castopod_phpmyadmin`: a phpmyadmin server to visualize the mariadb + > database. + +2. Run any command inside the containers by prefixing them with + `docker-compose run --rm app`: + + ```bash + # use PHP + docker-compose run --rm app php -v + + # use Composer + docker-compose run --rm app composer -V + + # use npm + docker-compose run --rm app npm -v + + # use git + docker-compose run --rm app git version + ``` + +--- + +## Going Further + +### Install Castopod's dependencies + +1. Install php dependencies with [Composer](https://getcomposer.org/) + + ```bash + composer install + ``` + + ::: info Note + + The php dependencies aren't included in the repository. Composer will check + the `composer.json` and `composer.lock` files to download the packages with + the right versions. The dependencies will live under the `vendor/` folder. + For more info, check out the + [Composer documentation](https://getcomposer.org/doc/). + + ::: + +2. Install javascript dependencies with [npm](https://www.npmjs.com/) + + ```bash + npm install + ``` + + ::: info Note + + The javascript dependencies aren't included in the repository. Npm will check + the `package.json` and `package.lock` files to download the packages with the + right versions. The dependencies will live under the `node_module` folder. + For more info, check out the [NPM documentation](https://docs.npmjs.com/). + + ::: + +3. Generate static assets: + + ```bash + # build all static assets at once + npm run build:static + + # build specific assets + npm run build:icons + npm run build:svg + ``` + + ::: info Note + + The static assets generated live under the `public/assets` folder, it + includes javascript, styles, images, fonts, icons and svg files. + + ::: + +### Initialize and populate database + +::: tip Tip + +You may skip this section if you go through the install wizard (go to +`/cp-install`). + +::: + +1. Build the database with the migrate command: + + ```bash + # loads the database schema during first migration + php spark migrate -all + ``` + + You may need to undo the migration (rollback): + + ```bash + # rolls back database schema (deletes all tables and their content) + php spark migrate:rollback + ``` + +2. Populate the database with the required data: + + ```bash + # Populates all required data + php spark db:seed AppSeeder + ``` + + You may choose to add data separately: + + ```bash + # Populates all categories + php spark db:seed CategorySeeder + + # Populates all Languages + php spark db:seed LanguageSeeder + + # Populates all podcasts platforms + php spark db:seed PlatformSeeder + + # Populates all Authentication data (roles definition…) + php spark db:seed AuthSeeder + ``` + +3. (optionnal) Populate the database with test data: + + - Populate test data (login: admin / password: AGUehL3P) + + ```bash + php spark db:seed TestSeeder + ``` + + - Populate with fake podcast analytics: + + ```bash + php spark db:seed FakePodcastsAnalyticsSeeder + ``` + + - Populate with fake website analytics: + + ```bash + php spark db:seed FakeWebsiteAnalyticsSeeder + ``` + + TestSeeder will add an active superadmin user with the following credentials: + + - username: **admin** + - password: **AGUehL3P** + +### Useful docker / docker-compose commands + +- Monitor the app container: + +```bash +docker-compose logs --tail 50 --follow --timestamps app +``` + +- Interact with redis server using included redis-cli command: + +```bash +docker exec -it castopod_redis redis-cli +``` + +- Monitor the redis container: + +```bash +docker-compose logs --tail 50 --follow --timestamps redis +``` + +- Monitor the mariadb container: + +```bash +docker-compose logs --tail 50 --follow --timestamps mariadb +``` + +- Monitor the phpmyadmin container: + +```bash +docker-compose logs --tail 50 --follow --timestamps phpmyadmin +``` + +- Restart docker containers: + +```bash +docker-compose restart +``` + +- Destroy all containers, opposite of `up` command: + +```bash +docker-compose down +``` + +- Rebuild app container: + +```bash +docker-compose build app +``` + +Check [docker](https://docs.docker.com/engine/reference/commandline/docker/) and +[docker-compose](https://docs.docker.com/compose/reference/) documentations for +more insights. + +## Known issues + +### Allocation failed - JavaScript heap out of memory + +This happens when running `npm install`. + +👉 By default, docker might not have access to enough RAM. Allocate more memory +and run `npm install` again. + +### (Linux) Files created inside container are attributed to root locally + +You may use Linux user namespaces to fix this on your machine: + +::: info Note + +Replace "username" with your local username + +::: + +1. Go to `/etc/docker/daemon.json` and add: + + ```json + { + "userns-remap": "username" + } + ``` + +2. Configure the subordinate uid/guid: + + ```bash + # in /etc/subuid + username:1000:1 + username:100000:65536 + ``` + + ```bash + # in /etc/subgid + username:1000:1 + username:100000:65536 + ``` + +3. Restart docker: + + ```bash + sudo systemctl restart docker + ``` + +4. That's it! Now, the root user in the container will be mapped to the user on + your local machine, no more permission issues! 🎉 + +You can check +[this great article](https://www.jujens.eu/posts/en/2017/Jul/02/docker-userns-remap/) +to know more about how it works. diff --git a/docs/src/sv/getting-started/_category_.json b/docs/src/sv/getting-started/_category_.json new file mode 100644 index 00000000..877a378f --- /dev/null +++ b/docs/src/sv/getting-started/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Getting Started", + "position": 2 +}