docs: add Brazilian Portuguese and Norwegian Nynorsk languages
This commit is contained in:
parent
e787b6b6e7
commit
e9adc216e4
|
@ -1,9 +1,6 @@
|
||||||
import { defineConfig } from "vitepress";
|
import { defineConfig } from "vitepress";
|
||||||
|
|
||||||
export default defineConfig({
|
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",
|
srcDir: "src",
|
||||||
|
|
||||||
head: [
|
head: [
|
||||||
|
@ -26,7 +23,7 @@ export default defineConfig({
|
||||||
{
|
{
|
||||||
property: "og:image:alt",
|
property: "og:image:alt",
|
||||||
content:
|
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/" }],
|
["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: {
|
themeConfig: {
|
||||||
logo: "/images/castopod-icon.svg",
|
logo: "/images/castopod-icon.svg",
|
||||||
lastUpdated: "Last Updated",
|
lastUpdated: "Last Updated",
|
||||||
|
@ -50,27 +68,74 @@ export default defineConfig({
|
||||||
docsDir: "docs/src",
|
docsDir: "docs/src",
|
||||||
docsBranch: "develop",
|
docsBranch: "develop",
|
||||||
editLinks: true,
|
editLinks: true,
|
||||||
nav: [
|
locales: {
|
||||||
{
|
"/": {
|
||||||
text: "Home",
|
label: "English",
|
||||||
link: "https://castopod.org/",
|
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(),
|
||||||
|
},
|
||||||
},
|
},
|
||||||
{
|
"/pt-BR/": {
|
||||||
text: "Blog",
|
label: "Português do Brasil",
|
||||||
link: "https://blog.castopod.org/",
|
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() },
|
||||||
},
|
},
|
||||||
{
|
"/nn-NO/": {
|
||||||
text: "Github",
|
label: "Norsk nynorsk",
|
||||||
link: "https://github.com/ad-aures/castopod",
|
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 [
|
return [
|
||||||
{
|
{
|
||||||
text: "Introduction",
|
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
|
contributing
|
||||||
getting-started
|
getting-started
|
||||||
index.md
|
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
|
### Initialize and populate database
|
||||||
|
|
||||||
::: tip
|
::: tip Tip
|
||||||
|
|
||||||
You may skip this section if you go through the install wizard (go to
|
You may skip this section if you go through the install wizard (go to
|
||||||
`/cp-install`).
|
`/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).
|
> We recommend using [MariaDB](https://mariadb.org).
|
||||||
|
|
||||||
::: warning
|
::: warning Warning
|
||||||
|
|
||||||
Castopod only works with supported MySQL 5.7 or higher compatible databases. It
|
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
|
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).
|
> 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
|
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
|
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/)
|
[GNU Affero General Public License v3.0](https://choosealicense.com/licenses/agpl-3.0/)
|
||||||
|
|
||||||
Copyright © 2020-d.d., [Ad Aures](https://adaures.com/).
|
Copyright © 2020-present, [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
|
|
||||||
|
|
||||||
[release]: https://code.castopod.org/adaures/castopod/-/releases
|
[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]: 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]: 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]: 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]: https://castopod.org/discord
|
||||||
|
[discord-badge]: https://img.shields.io/badge/chat-on%20discord-7389D8
|
||||||
[stars]: https://github.com/ad-aures/castopod/stargazers
|
[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]: 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).
|
> 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.
|
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
|
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/)
|
[Licença Pública Geral GNU Affero v3.0](https://choosealicense.com/licenses/agpl-3.0/)
|
||||||
|
|
||||||
Copyright © 2020-presente, [Ad Aures](https://adaures.com/).
|
Copyright © 2020-present, [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
|
|
||||||
|
|
||||||
[release]: https://code.castopod.org/adaures/castopod/-/releases
|
[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]: 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]: 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]: 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]: https://castopod.org/discord
|
||||||
|
[discord-badge]: https://img.shields.io/badge/chat-on%20discord-7389D8
|
||||||
[stars]: https://github.com/ad-aures/castopod/stargazers
|
[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]: 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