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