setup-development.md

Setup your development environment

Table of contents

• Introduction
• Prerequisites
• Start docker containers
• Initialize and populate database
• Install/Update app dependencies
• Start hacking
• Going Further
  • Useful docker / docker-compose commands
• Developing inside a Container
• Known issues

Introduction

Castopod 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!

Prerequisites

0. Install docker desktop.

1. Clone castopod project by running:

git clone https://code.podlibre.org/podlibre/castopod.git

2. Create a .env file with the minimum required config to connect the app to the database:

CI_ENVIRONMENT="development"

database.default.hostname="mariadb"
database.default.database="castopod"
database.default.username="podlibre"
database.default.password="castopod"

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. Add the repository you've cloned to docker desktop's Settings > Resources > File Sharing.
4. Install castopod's php dependencies

The project's php dependencies aren't included in the repository, you have to download them using the composer service defined in docker-compose.yml

docker-compose run --rm composer install --ignore-platform-reqs

5. Install castopod's js dependencies

The project's js dependencies aren't included in the repository, you have to download them using the node service defined in docker-compose.yml

docker-compose run --rm node npm install

6. Build assets: javascript, styles, icons and svg images

To generate public assets, you must run the following commands.

docker-compose run --rm node npm run build:js
docker-compose run --rm node npm run build:css
docker-compose run --rm node npm run build:icons
docker-compose run --rm node npm run build:svg
docker-compose run --rm node npm run copy:images
docker-compose run --rm node npm run copy:fonts

Start docker containers

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 ps

# Alternatively, you can check all processes (you should see composer with an Exited status)
docker ps -a

The docker-compose up -d command will boot 3 containers in the background:

• castopod_app: a php based container with codeigniter requirements installed
• castopod_mariadb: a mariadb server for persistent data
• castopod_phpmyadmin: a phpmyadmin server to visualize the mariadb database

NB. ./mariadb, ./phpmyadmin folders will be mounted in the project's root directory to persist data and logs.

Initialize and populate database

1. Build the database with the migrate command:

# loads the database schema during first migration
docker-compose run --rm app php spark migrate -all

In case you need to roll back, use this command:

# rolls back database schema loading (deletes all tables and their content)
docker-compose run --rm app php spark migrate:rollback

2. Populate the database with the required data:

# Populates all required data
docker-compose run --rm app php spark db:seed AppSeeder

You may also add only data you chose:

# Populates all categories
docker-compose run --rm app php spark db:seed CategorySeeder
# Populates all Languages
docker-compose run --rm app php spark db:seed LanguageSeeder
# Populates all podcasts platforms
docker-compose run --rm app php spark db:seed PlatformSeeder
# Populates all Authentication data (roles definition…)
docker-compose run --rm app php spark db:seed AuthSeeder
# Populates test data (login: admin / password: AGUehL3P)
docker-compose run --rm app php spark db:seed TestSeeder

3. (optionnal) Populate the database with test data:

docker-compose run --rm app php spark db:seed TestSeeder

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

• username: admin
• password: AGUehL3P

Install/Update app dependencies

Castopod uses composer to manage php dependencies and npm to manage javascript dependencies.

You can install / update the project's dependencies using both composer and node services:

# install php dependencies
docker-compose run --rm composer install --ignore-platform-reqs

# update php dependencies
docker-compose run --rm composer update --ignore-platform-reqs

NB. composer commands look for the composer.json file to find castopod's php dependencies, all of which live in the vendor/ folder. For more info, check out Composer documentation.

# install js dependencies
docker-compose run --rm node npm install

# update js dependencies
docker-compose run --rm node npm update

NB. npm commands look for the package.json file to find castopod's js dependencies, all of which live in the node_modules/ folder. For more info, check out NPM documentation.

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 app

• localhost:8888 for the phpmyadmin interface:

  • Username: podlibre
  • Password: castopod

---

Going Further

Useful docker / docker-compose commands

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

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

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

# restart docker containers
docker-compose restart

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

Check docker and docker-compose documentations for more insights.

Developing inside a Container

If you're working in VSCode, you can take advantage of the ./.devcontainer/ folder. It defines a development container with preinstalled VSCode extensions so you don't have to worry about them. The container will be loaded with php, composer and git:

1. Install the VSCode extension Remote - Containers
2. Ctrl/Cmd + Shift + P > Open in container

The VSCode window will reload inside the dev container.

You can check that the required packages are running in the console (Terminal > New Terminal):

php -v

composer -V

git version

For more info, see VSCode Remote Containers

Known issues

• Allocation failed - JavaScript heap out of memory when running npm install

  👉 By default, docker might not have access to enough RAM. Allocate more memory and run npm install again.