Skip to content

Latest commit

 

History

History
96 lines (72 loc) · 4.6 KB

local-dev.md

File metadata and controls

96 lines (72 loc) · 4.6 KB
Raw

Local Development of the calendar

This file contains tips and tricks to help with local development of the calendar system. Please add to it as you find 'gotchas' or tips.

How does this all work?

By moving to docker, your local development should run much more like production and dependencies (like setting up an LDAP endpoint) are handled automatically. docker-compose.yml (and it's cousin docker-compose.prod.yml) contain the definitions of our docker 'environment', allowing (once docker-compose and docker are setup) anyone to simply run docker compose up and start a local calendar system.

The local folder is mapped (volume bind) through docker, so for most cases changes are immediately visible (no restart / reload required). Exceptions to this include:

  • Changes to docker (docker-compose.yml or Dockerfile)
    • Docker has to be restarted for these to take effect. In some cases additional steps are needed to clean up the docker environment.
  • Changes to composer (PHP requirements)
    • Since the composer install happens at 'build' time, a new container has to be built for those changes to take place.

We also local bind a few folders to make development easier:

  • logs/www will contain the logs generated by Cake PHP
    • error.log is a good place to look for details when Cake throws an error
  • logs/var/apache2 contains the apache logs
    • error.log can be useful if your php system isn't starting (note that not defined errors are typical in this file and should be ignored)
    • access.log logs the requests that reach the web server (a good place to start if you're not getting the expected response)
  • vendor are all the dependencies installed from Composer and Cake PHP. For the most part, you'll ignore this but having it mapped outside of the container allows some IDEs to enable better auto-complete etc.

Xdebug

When someone understands how we're using Xdebug can they please update this section?

FAQ

  • I get open dms-ad-openldap/docker-compose.yml: no such file or directory

    • You've likely skipped a step in the setup and didn't get a recursive clone of the repo. Run git submodule update --init to correct it (and consider re-reading the quick start 😉)

  • I keep getting errors like Error response from daemon: error while creating mount source path ... permission denied

    • This seems to happen on *nix environments and you can either continue running docker compose up until all the local volumes are created (logs/www, logs/var, tmp, vendor). Or you can run ./setup.sh which will create those paths for you ahead of time.

  • I get an error from docker compose up that DEBUG has an invalid value

    • Please make sure you are running version 2+ of docker-compose (check with docker compose -v)

  • Docker won't start with errors like Error response from daemon: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: permission denied: unknown

    • The scripts in .docker/ (*.sh) should be marked as executable (you can run chmod +x .docker/*.sh to fix)

  • How do we test with traefik locally?

    • I'm not sure (yet!) ... someone will have to update this with more details

Old (pre-docker) instructions for local development

These won't apply to most people, but are being kept for anyone that wants to run the PHP code directly (without docker).

Installation

  1. Download Composer or update composer self-update.
  2. Run php composer.phar install.

You should now have all of the components needed to run a local version of the calendar application. Check this by ensuring that the vendor directory in the root folder contains several folders with imported packages.

Configuration

Use migrate command to create database. There are also several database seeders which can add some initial data to your database for event categories, committees, configurations, prerequisites, rooms and tools. More information on how to run those seeders is available in the CakePHP Cookbook

Copy the config/app.default.php file to config/app.php. This file is a mirror of the config file on the production server with accounts and other sensitive information removed.

The .htaccess-sample file in the root directory can, in most cases, be renamed to .htaccess and provide everything needed for CakePHP to route necessary traffic to the webroot directory.