From cdeb8bf26e7a34fc2225149e198199ed9a8a6bd4 Mon Sep 17 00:00:00 2001 From: Yassine Doghri Date: Wed, 6 Mar 2024 12:41:50 +0000 Subject: [PATCH] build(devcontainer): add migration and DevSeed command to run post devcontainer creation update dev setup docs + build and deploy docs everytime --- .devcontainer/devcontainer.json | 2 +- .gitlab-ci.yml | 3 - app/Database/Seeds/DevSeeder.php | 26 ++ app/Database/Seeds/DevSuperadminSeeder.php | 48 ++ .../Seeds/FakeSinglePodcastApiSeeder.php | 2 +- app/Database/Seeds/TestSeeder.php | 49 -- 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/index.md | 2 +- 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/index.md | 2 +- docs/src/contributing/setup-development.md | 61 +-- docs/src/da/index.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/index.md | 2 +- 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/index.md | 2 +- 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/index.md | 2 +- docs/src/fa/index.md | 2 +- 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/index.md | 2 +- docs/src/fr2/index.md | 2 +- docs/src/fr_CA/index.md | 2 +- docs/src/gd/index.md | 2 +- docs/src/gl/index.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/index.md | 2 +- 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/index.md | 2 +- docs/src/ja/index.md | 2 +- docs/src/kk/index.md | 2 +- docs/src/ko/index.md | 2 +- 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/index.md | 2 +- docs/src/nn-NO/contributing/_category_.json | 4 - docs/src/nn-NO/contributing/guidelines.md | 154 ------- .../nn-NO/contributing/setup-development.md | 423 ----------------- docs/src/nn-NO/index.md | 2 +- 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/index.md | 2 +- 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/index.md | 2 +- docs/src/pt-BR/contributing/_category_.json | 4 - docs/src/pt-BR/contributing/guidelines.md | 154 ------- .../pt-BR/contributing/setup-development.md | 423 ----------------- docs/src/pt-BR/index.md | 2 +- 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/index.md | 2 +- docs/src/ro/index.md | 2 +- 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/index.md | 2 +- docs/src/sv/contributing/_category_.json | 4 - docs/src/sv/contributing/guidelines.md | 154 ------- docs/src/sv/contributing/setup-development.md | 424 ------------------ docs/src/uk/index.md | 2 +- 81 files changed, 126 insertions(+), 9414 deletions(-) create mode 100644 app/Database/Seeds/DevSeeder.php create mode 100644 app/Database/Seeds/DevSuperadminSeeder.php delete mode 100644 app/Database/Seeds/TestSeeder.php delete mode 100644 docs/src/ar/contributing/_category_.json delete mode 100644 docs/src/ar/contributing/guidelines.md delete mode 100644 docs/src/ar/contributing/setup-development.md delete mode 100644 docs/src/br/contributing/_category_.json delete mode 100644 docs/src/br/contributing/guidelines.md delete mode 100644 docs/src/br/contributing/setup-development.md delete mode 100644 docs/src/de/contributing/_category_.json delete mode 100644 docs/src/de/contributing/guidelines.md delete mode 100644 docs/src/de/contributing/setup-development.md delete mode 100644 docs/src/el/contributing/_category_.json delete mode 100644 docs/src/el/contributing/guidelines.md delete mode 100644 docs/src/el/contributing/setup-development.md delete mode 100644 docs/src/es/contributing/_category_.json delete mode 100644 docs/src/es/contributing/guidelines.md delete mode 100644 docs/src/es/contributing/setup-development.md delete mode 100644 docs/src/fr/contributing/_category_.json delete mode 100644 docs/src/fr/contributing/guidelines.md delete mode 100644 docs/src/fr/contributing/setup-development.md delete mode 100644 docs/src/id/contributing/_category_.json delete mode 100644 docs/src/id/contributing/guidelines.md delete mode 100644 docs/src/id/contributing/setup-development.md delete mode 100644 docs/src/it/contributing/_category_.json delete mode 100644 docs/src/it/contributing/guidelines.md delete mode 100644 docs/src/it/contributing/setup-development.md delete mode 100644 docs/src/nl/contributing/_category_.json delete mode 100644 docs/src/nl/contributing/guidelines.md delete mode 100644 docs/src/nl/contributing/setup-development.md delete mode 100644 docs/src/nn-NO/contributing/_category_.json delete mode 100644 docs/src/nn-NO/contributing/guidelines.md delete mode 100644 docs/src/nn-NO/contributing/setup-development.md delete mode 100644 docs/src/oc/contributing/_category_.json delete mode 100644 docs/src/oc/contributing/guidelines.md delete mode 100644 docs/src/oc/contributing/setup-development.md delete mode 100644 docs/src/pl/contributing/_category_.json delete mode 100644 docs/src/pl/contributing/guidelines.md delete mode 100644 docs/src/pl/contributing/setup-development.md delete mode 100644 docs/src/pt-BR/contributing/_category_.json delete mode 100644 docs/src/pt-BR/contributing/guidelines.md delete mode 100644 docs/src/pt-BR/contributing/setup-development.md delete mode 100644 docs/src/pt/contributing/_category_.json delete mode 100644 docs/src/pt/contributing/guidelines.md delete mode 100644 docs/src/pt/contributing/setup-development.md delete mode 100644 docs/src/ru/contributing/_category_.json delete mode 100644 docs/src/ru/contributing/guidelines.md delete mode 100644 docs/src/ru/contributing/setup-development.md delete mode 100644 docs/src/sv/contributing/_category_.json delete mode 100644 docs/src/sv/contributing/guidelines.md delete mode 100644 docs/src/sv/contributing/setup-development.md diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 0d4c4d97..a48dc081 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -5,7 +5,7 @@ "dockerComposeFile": ["../docker-compose.yml", "./docker-compose.yml"], "service": "app", "workspaceFolder": "/castopod", - "postCreateCommand": "composer install && pnpm install && pnpm run build:static", + "postCreateCommand": "composer install && pnpm install && pnpm run build:static && php spark migrate --all && php spark db:seed DevSeeder", "postStartCommand": "crontab ./crontab && cron && php spark serve --host 0.0.0.0", "postAttachCommand": "crontab ./crontab && service cron reload", "shutdownAction": "stopCompose", diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index c53056af..ee3acd7e 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -162,9 +162,6 @@ documentation: trigger: include: docs/.gitlab-ci.yml strategy: depend - only: - changes: - - docs/**/* docker: stage: build diff --git a/app/Database/Seeds/DevSeeder.php b/app/Database/Seeds/DevSeeder.php new file mode 100644 index 00000000..68feba40 --- /dev/null +++ b/app/Database/Seeds/DevSeeder.php @@ -0,0 +1,26 @@ +call('CategorySeeder'); + $this->call('LanguageSeeder'); + $this->call('PlatformSeeder'); + $this->call('DevSuperadminSeeder'); + } +} diff --git a/app/Database/Seeds/DevSuperadminSeeder.php b/app/Database/Seeds/DevSuperadminSeeder.php new file mode 100644 index 00000000..c852d9d1 --- /dev/null +++ b/app/Database/Seeds/DevSuperadminSeeder.php @@ -0,0 +1,48 @@ +where('is_owner', true)->first() instanceof User) { + return; + } + + /** + * Inserts an owner with the following credentials: admin: `admin@example.com` password: `castopod` + */ + + // Get the User Provider (UserModel by default) + $users = auth() + ->getProvider(); + + $user = new User([ + 'username' => 'admin', + 'email' => 'admin@castopod.local', + 'password' => 'castopod', + 'is_owner' => true, + ]); + $users->save($user); + + // To get the complete user object with ID, we need to get from the database + $user = $users->findById($users->getInsertID()); + + $user->addGroup(setting('AuthGroups.mostPowerfulGroup')); + } +} diff --git a/app/Database/Seeds/FakeSinglePodcastApiSeeder.php b/app/Database/Seeds/FakeSinglePodcastApiSeeder.php index 7c31e606..e07bf66b 100644 --- a/app/Database/Seeds/FakeSinglePodcastApiSeeder.php +++ b/app/Database/Seeds/FakeSinglePodcastApiSeeder.php @@ -189,7 +189,7 @@ class FakeSinglePodcastApiSeeder extends Seeder public function run(): void { $this->call(AppSeeder::class); - $this->call(TestSeeder::class); + $this->call(DevSeeder::class); $this->db->table('media') ->insert(self::cover()); $this->db->table('media') diff --git a/app/Database/Seeds/TestSeeder.php b/app/Database/Seeds/TestSeeder.php deleted file mode 100644 index 7bd2b2a4..00000000 --- a/app/Database/Seeds/TestSeeder.php +++ /dev/null @@ -1,49 +0,0 @@ -db->table('users') - ->insert([ - 'id' => 1, - 'username' => 'admin', - 'is_owner' => 1, - ]); - - $this->db->table('auth_identities') - ->insert([ - 'id' => 1, - 'user_id' => 1, - 'type' => 'email_password', - 'secret' => 'admin@example.com', - 'secret2' => '$2y$10$TXJEHX/djW8jtzgpDVf7dOOCGo5rv1uqtAYWdwwwkttQcDkAeB2.6', - ]); - - $this->db - ->table('auth_groups_users') - ->insert([ - 'user_id' => 1, - 'group' => setting('AuthGroups.mostPowerfulGroup'), - ]); - } -} diff --git a/docs/src/ar/contributing/_category_.json b/docs/src/ar/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/ar/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/ar/contributing/guidelines.md b/docs/src/ar/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/ar/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/ar/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/ar/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/ar/index.md +++ b/docs/src/ar/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/br/contributing/_category_.json b/docs/src/br/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/br/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/br/contributing/guidelines.md b/docs/src/br/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/br/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/br/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/br/index.md index d47a43ff..96100dbf 100644 --- a/docs/src/br/index.md +++ b/docs/src/br/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/contributing/setup-development.md b/docs/src/contributing/setup-development.md index 82e4a8fd..b996bac7 100644 --- a/docs/src/contributing/setup-development.md +++ b/docs/src/contributing/setup-development.md @@ -34,7 +34,7 @@ to help you kickstart your contribution. ```ini CI_ENVIRONMENT="development" - # If set to development, you must run `npm run dev` to start the static assets server + # If set to development, you must run `pnpm run dev` to start the static assets server vite.environment="development" # By default, this is set to true in the app config. @@ -106,7 +106,7 @@ required services will be loaded automagically! 🪄 ```bash # run Vite dev server - npm run dev + pnpm run dev ``` If there is any issue with the php server not running, you can restart them @@ -129,8 +129,8 @@ required services will be loaded automagically! 🪄 # Composer is installed composer -V - # npm is installed - npm -v + # pnpm is installed + pnpm -v # git is installed git version @@ -148,7 +148,12 @@ more insights. To see your changes, go to: -- `http://localhost:8080/` for the Castopod app +- `http://localhost:8080/` for the Castopod website +- `http://localhost:8080/cp-admin` for the Castopod admin: + + - email: **admin@castopod.local** + - password: **castopod** + - `http://localhost:8888/` for the phpmyadmin interface: - username: **castopod** @@ -197,8 +202,8 @@ You do not wish to use the VSCode devcontainer? No problem! # use Composer docker-compose run --rm app composer -V - # use npm - docker-compose run --rm app npm -v + # use pnpm + docker-compose run --rm app pnpm -v # use git docker-compose run --rm app git version @@ -226,18 +231,18 @@ You do not wish to use the VSCode devcontainer? No problem! ::: -2. Install javascript dependencies with [npm](https://www.npmjs.com/) +2. Install javascript dependencies with [pnpm](https://pnpm.io/) ```bash - npm install + pnpm 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/). + The javascript dependencies aren't included in the repository. Pnpm will + check the `package.json` and `pnpm-lock.yaml` files to download the packages + with the right versions. The dependencies will live under the `node_module` + folder. For more info, check out the [PNPM documentation](https://pnpm.io/). ::: @@ -245,11 +250,11 @@ You do not wish to use the VSCode devcontainer? No problem! ```bash # build all static assets at once - npm run build:static + pnpm run build:static # build specific assets - npm run build:icons - npm run build:svg + pnpm run build:icons + pnpm run build:svg ``` ::: info Note @@ -286,7 +291,7 @@ You may skip this section if you go through the install wizard (go to ```bash # Populates all required data - php spark db:seed AppSeeder + php spark db:seed DevSeeder ``` You may choose to add data separately: @@ -301,18 +306,12 @@ You may skip this section if you go through the install wizard (go to # Populates all podcasts platforms php spark db:seed PlatformSeeder - # Populates all Authentication data (roles definition…) - php spark db:seed AuthSeeder + # Adds a superadmin with [admin@castopod.local / castopod] credentials + php spark db:seed PlatformSeeder ``` 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 @@ -325,11 +324,6 @@ You may skip this section if you go through the install wizard (go to 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: @@ -386,13 +380,6 @@ 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: diff --git a/docs/src/da/index.md b/docs/src/da/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/da/index.md +++ b/docs/src/da/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/de/contributing/_category_.json b/docs/src/de/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/de/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/de/contributing/guidelines.md b/docs/src/de/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/de/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/de/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/de/index.md index b8f6140f..92062c7a 100644 --- a/docs/src/de/index.md +++ b/docs/src/de/index.md @@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/el/contributing/_category_.json b/docs/src/el/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/el/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/el/contributing/guidelines.md b/docs/src/el/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/el/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/el/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/el/index.md index c71137b8..bc25620f 100644 --- a/docs/src/el/index.md +++ b/docs/src/el/index.md @@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/es/contributing/_category_.json b/docs/src/es/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/es/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/es/contributing/guidelines.md b/docs/src/es/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/es/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/es/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/es/index.md index cf1c8e40..d948f885 100644 --- a/docs/src/es/index.md +++ b/docs/src/es/index.md @@ -167,7 +167,7 @@ so that you can understand what actions will and will not be tolerated. ### Guía para colaborar -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/fa/index.md b/docs/src/fa/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/fa/index.md +++ b/docs/src/fa/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/fr/contributing/_category_.json b/docs/src/fr/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/fr/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/fr/contributing/guidelines.md b/docs/src/fr/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/fr/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/fr/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/fr/index.md index 5a8d9bdf..c84a8387 100644 --- a/docs/src/fr/index.md +++ b/docs/src/fr/index.md @@ -163,7 +163,7 @@ so that you can understand what actions will and will not be tolerated. ### Guide de contribution -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/fr2/index.md b/docs/src/fr2/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/fr2/index.md +++ b/docs/src/fr2/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/fr_CA/index.md b/docs/src/fr_CA/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/fr_CA/index.md +++ b/docs/src/fr_CA/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/gd/index.md b/docs/src/gd/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/gd/index.md +++ b/docs/src/gd/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/gl/index.md b/docs/src/gl/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/gl/index.md +++ b/docs/src/gl/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/id/contributing/_category_.json b/docs/src/id/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/id/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/id/contributing/guidelines.md b/docs/src/id/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/id/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/id/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/id/index.md index 58415ff2..70dbeb5e 100644 --- a/docs/src/id/index.md +++ b/docs/src/id/index.md @@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated. ### Panduan berkontribusi -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/it/contributing/_category_.json b/docs/src/it/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/it/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/it/contributing/guidelines.md b/docs/src/it/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/it/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/it/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/it/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/it/index.md +++ b/docs/src/it/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/ja/index.md b/docs/src/ja/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/ja/index.md +++ b/docs/src/ja/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/kk/index.md b/docs/src/kk/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/kk/index.md +++ b/docs/src/kk/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/ko/index.md b/docs/src/ko/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/ko/index.md +++ b/docs/src/ko/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/nl/contributing/_category_.json b/docs/src/nl/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/nl/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/nl/contributing/guidelines.md b/docs/src/nl/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/nl/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/nl/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/nl/index.md index 12ac44f3..ee8c0132 100644 --- a/docs/src/nl/index.md +++ b/docs/src/nl/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/nn-NO/contributing/_category_.json b/docs/src/nn-NO/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/nn-NO/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/nn-NO/contributing/guidelines.md b/docs/src/nn-NO/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/nn-NO/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/nn-NO/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/nn-NO/index.md index dab9b77e..df53e5d1 100644 --- a/docs/src/nn-NO/index.md +++ b/docs/src/nn-NO/index.md @@ -164,7 +164,7 @@ så du veit kva slags åtferd me godtek og ikkje. ### Korleis bidra -Les gjerne [korleis du bidreg](./contributing/guidelines.md) for å læra korleis +Les gjerne [korleis du bidreg](../contributing/guidelines.md) for å læra korleis me utviklar Castopod, korleis me føreslær rettingar og forbetringar, og korleis me byggjer og prøver ut endringar i programmet. diff --git a/docs/src/oc/contributing/_category_.json b/docs/src/oc/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/oc/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/oc/contributing/guidelines.md b/docs/src/oc/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/oc/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/oc/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/oc/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/oc/index.md +++ b/docs/src/oc/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/pl/contributing/_category_.json b/docs/src/pl/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/pl/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/pl/contributing/guidelines.md b/docs/src/pl/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/pl/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/pl/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/pl/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/pl/index.md +++ b/docs/src/pl/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/pt-BR/contributing/_category_.json b/docs/src/pt-BR/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/pt-BR/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/pt-BR/contributing/guidelines.md b/docs/src/pt-BR/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/pt-BR/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/pt-BR/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/pt-BR/index.md index 84bbb788..38593f36 100644 --- a/docs/src/pt-BR/index.md +++ b/docs/src/pt-BR/index.md @@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated. ### Guia de contribuição -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/pt/contributing/_category_.json b/docs/src/pt/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/pt/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/pt/contributing/guidelines.md b/docs/src/pt/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/pt/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/pt/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/pt/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/pt/index.md +++ b/docs/src/pt/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/ro/index.md b/docs/src/ro/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/ro/index.md +++ b/docs/src/ro/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/ru/contributing/_category_.json b/docs/src/ru/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/ru/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/ru/contributing/guidelines.md b/docs/src/ru/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/ru/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index 7e42892a..00000000 --- a/docs/src/ru/contributing/setup-development.md +++ /dev/null @@ -1,423 +0,0 @@ ---- -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/" - media.baseURL="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/index.md b/docs/src/ru/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/ru/index.md +++ b/docs/src/ru/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod. diff --git a/docs/src/sv/contributing/_category_.json b/docs/src/sv/contributing/_category_.json deleted file mode 100644 index e12f1ce5..00000000 --- a/docs/src/sv/contributing/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Contributing", - "position": 3 -} diff --git a/docs/src/sv/contributing/guidelines.md b/docs/src/sv/contributing/guidelines.md deleted file mode 100644 index 1a53c89e..00000000 --- a/docs/src/sv/contributing/guidelines.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -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 deleted file mode 100644 index b8f87717..00000000 --- a/docs/src/sv/contributing/setup-development.md +++ /dev/null @@ -1,424 +0,0 @@ ---- -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 `pnpm 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/" - media.baseURL="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 - pnpm 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 - - # pnpm is installed - pnpm -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 pnpm - docker-compose run --rm app pnpm -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 [pnpm](https://pnpm.io/) - - ```bash - pnpm install - ``` - - ::: info Note - - The javascript dependencies aren't included in the repository. pnPM will - check the `package.json` and `pnpm-lock.yaml` files to download the packages - with the right versions. The dependencies will live under the `node_module` - folder. For more info, check out the - [pnPM documentation](https://pnpm.io/motivation). - - ::: - -3. Generate static assets: - - ```bash - # build all static assets at once - pnpm run build:static - - # build specific assets - pnpm run build:icons - pnpm 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 `pnpm install`. - -👉 By default, docker might not have access to enough RAM. Allocate more memory -and run `pnpm 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/uk/index.md b/docs/src/uk/index.md index b63ff645..7f012c6c 100644 --- a/docs/src/uk/index.md +++ b/docs/src/uk/index.md @@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated. ### Contributing guide -Read our [contributing guide](./contributing/guidelines.md) to learn about our +Read our [contributing guide](../contributing/guidelines.md) to learn about our development process, how to propose bugfixes and improvements, and how to build and test your changes to Castopod.