castopod/docs/setup-development.md

Setup your development environment

Table of contents

• Introduction
• Pre-requisites
• (recommended) Develop inside the app Container with VSCode
• (not-recommended) Develop outside the app container
• Install Castopod Host's dependencies
• Initialize and populate database
• Start hacking
• Going Further
  • Useful docker / docker-compose commands
• Known issues
  • Allocation failed - JavaScript heap out of memory
  • Files created inside container are attributed to root locally (Linux)

Introduction

Castopod Host is a web app based on the php framework CodeIgniter 4.

To setup a dev environment, we use Docker. A docker-compose.yml and Dockerfile are included in the project's root folder to help you kickstart your contribution.

Know that 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!

Pre-requisites

0. Install docker.

1. Clone Castopod Host project by running:

   git clone https://code.podlibre.org/podlibre/castopod-host.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:

   CI_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/"
   
   app.adminGateway="cp-admin"
   app.authGateway="cp-auth"
   
   database.default.hostname="mariadb"
   database.default.database="castopod"
   database.default.username="podlibre"
   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 for more info.

3. (for docker desktop) Add the repository you've cloned to docker desktop's Settings > Resources > File Sharing

(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

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 Host's php server. During development, you will have to start Vite's dev server for compiling the typescript code and styles:

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

   # run Castopod host server
   php spark serve --host 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:

   # 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

(not-recommended) 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:

   # 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-host_app: a php based container with CodeIgniter4 requirements installed
   • castopod-host_redis: a redis database to handle queries and pages caching
   • castopod-host_mariadb: a mariadb server for persistent data
   • castopod-host_phpmyadmin: a phpmyadmin server to visualize the mariadb database.

2. Run any command by prefixing them with docker-compose run --rm app:

   # 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
   

Install Castopod Host's dependencies

1. Install php dependencies with Composer

   composer install
   

   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.

2. Install javascript dependencies with npm

   npm install
   

   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.

3. Generate static assets:

   # build all assets at once
   npm run build:static
   
   # generate/copy specific assets
   npm run build:icons
   npm run build:svg
   npm run copy:images
   

   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

Note:

You may skip this section if you go through the install wizard (go to /cp-install).

1. Build the database with the migrate command:

   # loads the database schema during first migration
   php spark migrate -all
   

   You may need to undo the migration (rollback):

   # rolls back database schema (deletes all tables and their content)
   php spark migrate:rollback
   

2. Populate the database with the required data:

   # Populates all required data
   php spark db:seed AppSeeder
   

   You may choose to add data separately:

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

   # Populates test data (login: admin / password: AGUehL3P)
   php spark db:seed TestSeeder
   
   # Populates with fake podcast analytics
   php spark db:seed FakePodcastsAnalyticsSeeder
   
   # Populates with fake website analytics
   php spark db:seed FakeWebsiteAnalyticsSeeder
   

   TestSeeder will add an active superadmin user with the following credentials:

   • username: admin
   • password: AGUehL3P

Start hacking

You're all set! Start working your magic by updating the project's files! Help yourself to the CodeIgniter4 User Guide for more insights.

To see your changes, go to:

• localhost:8080 for the Castopod Host app

• localhost:8888 for the phpmyadmin interface:

  • username: podlibre
  • password: castopod

---

Going Further

Useful docker / docker-compose commands

# monitor the app container
docker-compose logs --tail 50 --follow --timestamps app

# interact with redis server using included redis-cli command
docker exec -it castopod-host_redis redis-cli

# monitor the redis container
docker-compose logs --tail 50 --follow --timestamps redis

# monitor the mariadb container
docker-compose logs --tail 50 --follow --timestamps mariadb

# monitor the phpmyadmin container
docker-compose logs --tail 50 --follow --timestamps phpmyadmin

# restart docker containers
docker-compose restart

# Destroy all containers, opposite of `up` command
docker-compose down

# Rebuild app container
docker-compose build app

Check docker and docker-compose 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.

Files created inside container are attributed to root locally (Linux)

You may use Linux user namespaces to fix this on your machine:

Note:

Replace "username" with your local username

1. Go to /etc/docker/daemon.json and add:

   {
     "userns-remap": "username"
   }
   

2. Configure the subordinate uid/guid:

   # in /etc/subuid
   username:1000:1
   username:100000:65536
   

   # in /etc/subgid
   username:1000:1
   username:100000:65536
   

3. Restart docker:

   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 to know more about how it works.