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:
parent
6289c42b11
commit
cdeb8bf26e
|
@ -5,7 +5,7 @@
|
||||||
"dockerComposeFile": ["../docker-compose.yml", "./docker-compose.yml"],
|
"dockerComposeFile": ["../docker-compose.yml", "./docker-compose.yml"],
|
||||||
"service": "app",
|
"service": "app",
|
||||||
"workspaceFolder": "/castopod",
|
"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",
|
"postStartCommand": "crontab ./crontab && cron && php spark serve --host 0.0.0.0",
|
||||||
"postAttachCommand": "crontab ./crontab && service cron reload",
|
"postAttachCommand": "crontab ./crontab && service cron reload",
|
||||||
"shutdownAction": "stopCompose",
|
"shutdownAction": "stopCompose",
|
||||||
|
|
|
@ -162,9 +162,6 @@ documentation:
|
||||||
trigger:
|
trigger:
|
||||||
include: docs/.gitlab-ci.yml
|
include: docs/.gitlab-ci.yml
|
||||||
strategy: depend
|
strategy: depend
|
||||||
only:
|
|
||||||
changes:
|
|
||||||
- docs/**/*
|
|
||||||
|
|
||||||
docker:
|
docker:
|
||||||
stage: build
|
stage: build
|
||||||
|
|
|
@ -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');
|
||||||
|
}
|
||||||
|
}
|
|
@ -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'));
|
||||||
|
}
|
||||||
|
}
|
|
@ -189,7 +189,7 @@ class FakeSinglePodcastApiSeeder extends Seeder
|
||||||
public function run(): void
|
public function run(): void
|
||||||
{
|
{
|
||||||
$this->call(AppSeeder::class);
|
$this->call(AppSeeder::class);
|
||||||
$this->call(TestSeeder::class);
|
$this->call(DevSeeder::class);
|
||||||
$this->db->table('media')
|
$this->db->table('media')
|
||||||
->insert(self::cover());
|
->insert(self::cover());
|
||||||
$this->db->table('media')
|
$this->db->table('media')
|
||||||
|
|
|
@ -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'),
|
|
||||||
]);
|
|
||||||
}
|
|
||||||
}
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -34,7 +34,7 @@ to help you kickstart your contribution.
|
||||||
|
|
||||||
```ini
|
```ini
|
||||||
CI_ENVIRONMENT="development"
|
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"
|
vite.environment="development"
|
||||||
|
|
||||||
# By default, this is set to true in the app config.
|
# By default, this is set to true in the app config.
|
||||||
|
@ -106,7 +106,7 @@ required services will be loaded automagically! 🪄
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# run Vite dev server
|
# 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
|
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 is installed
|
||||||
composer -V
|
composer -V
|
||||||
|
|
||||||
# npm is installed
|
# pnpm is installed
|
||||||
npm -v
|
pnpm -v
|
||||||
|
|
||||||
# git is installed
|
# git is installed
|
||||||
git version
|
git version
|
||||||
|
@ -148,7 +148,12 @@ more insights.
|
||||||
|
|
||||||
To see your changes, go to:
|
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:
|
- `http://localhost:8888/` for the phpmyadmin interface:
|
||||||
|
|
||||||
- username: **castopod**
|
- username: **castopod**
|
||||||
|
@ -197,8 +202,8 @@ You do not wish to use the VSCode devcontainer? No problem!
|
||||||
# use Composer
|
# use Composer
|
||||||
docker-compose run --rm app composer -V
|
docker-compose run --rm app composer -V
|
||||||
|
|
||||||
# use npm
|
# use pnpm
|
||||||
docker-compose run --rm app npm -v
|
docker-compose run --rm app pnpm -v
|
||||||
|
|
||||||
# use git
|
# use git
|
||||||
docker-compose run --rm app git version
|
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
|
```bash
|
||||||
npm install
|
pnpm install
|
||||||
```
|
```
|
||||||
|
|
||||||
::: info Note
|
::: info Note
|
||||||
|
|
||||||
The javascript dependencies aren't included in the repository. Npm will check
|
The javascript dependencies aren't included in the repository. Pnpm will
|
||||||
the `package.json` and `package.lock` files to download the packages with the
|
check the `package.json` and `pnpm-lock.yaml` files to download the packages
|
||||||
right versions. The dependencies will live under the `node_module` folder.
|
with the right versions. The dependencies will live under the `node_module`
|
||||||
For more info, check out the [NPM documentation](https://docs.npmjs.com/).
|
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
|
```bash
|
||||||
# build all static assets at once
|
# build all static assets at once
|
||||||
npm run build:static
|
pnpm run build:static
|
||||||
|
|
||||||
# build specific assets
|
# build specific assets
|
||||||
npm run build:icons
|
pnpm run build:icons
|
||||||
npm run build:svg
|
pnpm run build:svg
|
||||||
```
|
```
|
||||||
|
|
||||||
::: info Note
|
::: info Note
|
||||||
|
@ -286,7 +291,7 @@ You may skip this section if you go through the install wizard (go to
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Populates all required data
|
# Populates all required data
|
||||||
php spark db:seed AppSeeder
|
php spark db:seed DevSeeder
|
||||||
```
|
```
|
||||||
|
|
||||||
You may choose to add data separately:
|
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
|
# Populates all podcasts platforms
|
||||||
php spark db:seed PlatformSeeder
|
php spark db:seed PlatformSeeder
|
||||||
|
|
||||||
# Populates all Authentication data (roles definition…)
|
# Adds a superadmin with [admin@castopod.local / castopod] credentials
|
||||||
php spark db:seed AuthSeeder
|
php spark db:seed PlatformSeeder
|
||||||
```
|
```
|
||||||
|
|
||||||
3. (optionnal) Populate the database with test data:
|
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:
|
- Populate with fake podcast analytics:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
@ -325,11 +324,6 @@ You may skip this section if you go through the install wizard (go to
|
||||||
php spark db:seed FakeWebsiteAnalyticsSeeder
|
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
|
### Useful docker / docker-compose commands
|
||||||
|
|
||||||
- Monitor the app container:
|
- Monitor the app container:
|
||||||
|
@ -386,13 +380,6 @@ more insights.
|
||||||
|
|
||||||
## Known issues
|
## 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
|
### (Linux) Files created inside container are attributed to root locally
|
||||||
|
|
||||||
You may use Linux user namespaces to fix this on your machine:
|
You may use Linux user namespaces to fix this on your machine:
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -167,7 +167,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Guía para colaborar
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -163,7 +163,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Guide de contribution
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Panduan berkontribusi
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -164,7 +164,7 @@ så du veit kva slags åtferd me godtek og ikkje.
|
||||||
|
|
||||||
### Korleis bidra
|
### 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 utviklar Castopod, korleis me føreslær rettingar og forbetringar, og korleis
|
||||||
me byggjer og prøver ut endringar i programmet.
|
me byggjer og prøver ut endringar i programmet.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -160,7 +160,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Guia de contribuição
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
|
@ -1,4 +0,0 @@
|
||||||
{
|
|
||||||
"label": "Contributing",
|
|
||||||
"position": 3
|
|
||||||
}
|
|
|
@ -1,154 +0,0 @@
|
||||||
---
|
|
||||||
title: Guidelines
|
|
||||||
---
|
|
||||||
|
|
||||||
# Contributing to Castopod
|
|
||||||
|
|
||||||
Love Castopod and want to help? Thanks so much, there's something to do for
|
|
||||||
everybody!
|
|
||||||
|
|
||||||
Please take a moment to review this document in order to make the contribution
|
|
||||||
process easy and effective for everyone involved.
|
|
||||||
|
|
||||||
Following these guidelines helps to communicate that you respect the time of the
|
|
||||||
developers managing and developing this open source project. In return, they
|
|
||||||
should reciprocate that respect in addressing your issue or assessing patches
|
|
||||||
and features.
|
|
||||||
|
|
||||||
::: info Note
|
|
||||||
|
|
||||||
**Any** contribution made on a repository other than
|
|
||||||
[the original repository](https://code.castopod.org/adaures/castopod) will not
|
|
||||||
be accepted.
|
|
||||||
|
|
||||||
:::
|
|
||||||
|
|
||||||
## Using the issue tracker
|
|
||||||
|
|
||||||
The [issue tracker](https://code.castopod.org/adaures/castopod/-/issues) is the
|
|
||||||
preferred channel for [bug reports](#bug-reports),
|
|
||||||
[features requests](#feature-requests) and
|
|
||||||
[submitting pull requests](#pull-requests).
|
|
||||||
|
|
||||||
## ⚠️ Security issues and vulnerabilities
|
|
||||||
|
|
||||||
If you encounter any security issue or vulnerability in the Castopod source,
|
|
||||||
please contact us directly by email at
|
|
||||||
[security@castopod.org](mailto:security@castopod.org)
|
|
||||||
|
|
||||||
## Bug reports
|
|
||||||
|
|
||||||
A bug is a _demonstrable problem_ that is caused by the code in the repository.
|
|
||||||
Good bug reports are extremely helpful - thank you!
|
|
||||||
|
|
||||||
Guidelines for bug reports:
|
|
||||||
|
|
||||||
1. **Use the issue search** — check if the issue has already been
|
|
||||||
reported.
|
|
||||||
|
|
||||||
2. **Check if the issue has been fixed** — try to reproduce it using the
|
|
||||||
latest `main` branch in the repository.
|
|
||||||
|
|
||||||
3. **Isolate the problem** — ideally create a
|
|
||||||
[reduced test case](https://css-tricks.com/reduced-test-cases/) and a live
|
|
||||||
example.
|
|
||||||
|
|
||||||
A good bug report shouldn't leave others needing to chase you up for more
|
|
||||||
information. Please try to be as detailed as possible in your report. What is
|
|
||||||
your environment? What steps will reproduce the issue? What browser(s) and OS
|
|
||||||
experience the problem? What would you expect to be the outcome? All these
|
|
||||||
details will help people to fix any potential bugs.
|
|
||||||
|
|
||||||
> [Issue templates](https://docs.gitlab.com/ee/user/project/description_templates.html#using-the-templates)
|
|
||||||
> have been created for this project. You may use them to help you follow those
|
|
||||||
> guidelines.
|
|
||||||
|
|
||||||
## Feature requests
|
|
||||||
|
|
||||||
Feature requests are welcome. But take a moment to find out whether your idea
|
|
||||||
fits with the scope and aims of the project. It's up to _you_ to make a strong
|
|
||||||
case to convince the project's developers of the merits of this feature. Please
|
|
||||||
provide as much detail and context as possible.
|
|
||||||
|
|
||||||
## Pull requests
|
|
||||||
|
|
||||||
Good pull requests - patches, improvements, new features - are a fantastic help.
|
|
||||||
They should remain focused in scope and avoid containing unrelated commits.
|
|
||||||
|
|
||||||
**Please ask first** before embarking on any significant pull request (e.g.
|
|
||||||
implementing features, refactoring code, porting to a different language),
|
|
||||||
otherwise you risk spending a lot of time working on something that the
|
|
||||||
project's developers might not want to merge into the project.
|
|
||||||
|
|
||||||
Please adhere to the coding conventions used throughout a project (indentation,
|
|
||||||
accurate comments, etc.) and any other requirements (such as test coverage).
|
|
||||||
|
|
||||||
Adhering to the following process is the best way to get your work included in
|
|
||||||
the project:
|
|
||||||
|
|
||||||
1. [Fork](https://docs.gitlab.com/ee/gitlab-basics/fork-project.html) the
|
|
||||||
project, clone your fork, and configure the remotes:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Clone your fork of the repo into the current directory
|
|
||||||
git clone https://code.castopod.org/<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.
|
|
|
@ -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.
|
|
|
@ -159,7 +159,7 @@ so that you can understand what actions will and will not be tolerated.
|
||||||
|
|
||||||
### Contributing guide
|
### 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
|
development process, how to propose bugfixes and improvements, and how to build
|
||||||
and test your changes to Castopod.
|
and test your changes to Castopod.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue