setup-development.md

title: Development setup
sidebarDepth: 3

Setup your development environment

Introduction

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

We use Docker 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.

1. Clone Castopod project by running:

   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:

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

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

   # 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

3. 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:

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

   # 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 database to handle queries and pages caching
   • castopod_mariadb: a mariadb 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:

   # 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