rdelaage
/
castopod
mirror of https://code.castopod.org/adaures/castopod.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

build(devcontainer): add migration and DevSeed command to run post devcontainer creation 

update dev setup docs + build and deploy docs everytime
This commit is contained in:
Yassine Doghri 2024-03-06 12:41:50 +00:00
parent 6289c42b11
commit cdeb8bf26e
81 changed files with 126 additions and 9414 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.devcontainer/devcontainer.json
View File

@ -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",

3
.gitlab-ci.yml
View File

@ -162,9 +162,6 @@ documentation:
trigger:
include: docs/.gitlab-ci.yml
strategy: depend
only:
changes:
- docs/**/*
docker:
stage: build

26
app/Database/Seeds/DevSeeder.php Normal file
View File

@ -0,0 +1,26 @@
<?php
declare(strict_types=1);
/**
* Class AppSeeder Calls all required seeders for castopod to work properly
*
* @copyright 2020 Ad Aures
* @license https://www.gnu.org/licenses/agpl-3.0.en.html AGPL3
* @link https://castopod.org/
*/
namespace App\Database\Seeds;
use CodeIgniter\Database\Seeder;
class DevSeeder extends Seeder
{
public function run(): void
{
$this->call('CategorySeeder');
$this->call('LanguageSeeder');
$this->call('PlatformSeeder');
$this->call('DevSuperadminSeeder');
}
}

48
app/Database/Seeds/DevSuperadminSeeder.php Normal file
View File

@ -0,0 +1,48 @@
<?php
declare(strict_types=1);
/**
* Class TestSeeder Inserts a superadmin user in the database
*
* @copyright 2020 Ad Aures
* @license https://www.gnu.org/licenses/agpl-3.0.en.html AGPL3
* @link https://castopod.org/
*/
namespace App\Database\Seeds;
use CodeIgniter\Database\Seeder;
use CodeIgniter\Shield\Entities\User;
use Modules\Auth\Models\UserModel;
class DevSuperadminSeeder extends Seeder
{
public function run(): void
{
if ((new UserModel())->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'));
}
}

2
app/Database/Seeds/FakeSinglePodcastApiSeeder.php
View File

@ -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')

49
app/Database/Seeds/TestSeeder.php
View File

@ -1,49 +0,0 @@
<?php
declare(strict_types=1);
/**
* Class TestSeeder Inserts a superadmin user in the database
*
* @copyright 2020 Ad Aures
* @license https://www.gnu.org/licenses/agpl-3.0.en.html AGPL3
* @link https://castopod.org/
*/
namespace App\Database\Seeds;
use CodeIgniter\Database\Seeder;
class TestSeeder extends Seeder
{
public function run(): void
{
helper('setting');
/**
* Inserts an owner with the following credentials: admin: `admin@example.com` password: `AGUehL3P`
*/
$this->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'),
]);
}
}

4
docs/src/ar/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/ar/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/ar/contributing/setup-development.md
View File

@ -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.

2
docs/src/ar/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/br/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/br/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/br/contributing/setup-development.md
View File

@ -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.

2
docs/src/br/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

61
docs/src/contributing/setup-development.md
View File

@ -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:

2
docs/src/da/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/de/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/de/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/de/contributing/setup-development.md
View File

@ -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.

2
docs/src/de/index.md
View File

@ -160,7 +160,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/el/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/el/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/el/contributing/setup-development.md
View File

@ -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.

2
docs/src/el/index.md
View File

@ -160,7 +160,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/es/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/es/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/es/contributing/setup-development.md
View File

@ -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.

2
docs/src/es/index.md
View File

@ -167,7 +167,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/fa/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/fr/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/fr/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/fr/contributing/setup-development.md
View File

@ -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.

2
docs/src/fr/index.md
View File

@ -163,7 +163,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/fr2/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/fr_CA/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/gd/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/gl/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/id/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/id/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/id/contributing/setup-development.md
View File

@ -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.

2
docs/src/id/index.md
View File

@ -160,7 +160,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/it/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/it/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/it/contributing/setup-development.md
View File

@ -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.

2
docs/src/it/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/ja/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/kk/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/ko/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/nl/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/nl/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/nl/contributing/setup-development.md
View File

@ -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.

2
docs/src/nl/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/nn-NO/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/nn-NO/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/nn-NO/contributing/setup-development.md
View File

@ -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.

2
docs/src/nn-NO/index.md
View File

@ -164,7 +164,7 @@ så du veit kva slags åtferd me godtek og&nbsp;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.

4
docs/src/oc/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/oc/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/oc/contributing/setup-development.md
View File

@ -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.

2
docs/src/oc/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/pl/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/pl/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/pl/contributing/setup-development.md
View File

@ -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.

2
docs/src/pl/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/pt-BR/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/pt-BR/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/pt-BR/contributing/setup-development.md
View File

@ -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.

2
docs/src/pt-BR/index.md
View File

@ -160,7 +160,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/pt/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/pt/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/pt/contributing/setup-development.md
View File

@ -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.

2
docs/src/pt/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

2
docs/src/ro/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/ru/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/ru/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

423
docs/src/ru/contributing/setup-development.md
View File

@ -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.

2
docs/src/ru/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.

4
docs/src/sv/contributing/_category_.json
View File

@ -1,4 +0,0 @@
{
"label": "Contributing",
"position": 3
}

154
docs/src/sv/contributing/guidelines.md
View File

@ -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** &mdash; check if the issue has already been
reported.
2. **Check if the issue has been fixed** &mdash; try to reproduce it using the
latest `main` branch in the repository.
3. **Isolate the problem** &mdash; 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/<your-username>/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 <topic-branch-name>
```
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 <topic-branch-name>
```
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.

424
docs/src/sv/contributing/setup-development.md
View File

@ -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.

2
docs/src/uk/index.md
View File

@ -159,7 +159,7 @@ so that you can understand what actions will and will not be&nbsp;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.