Skip to content

Latest commit

 

History

History
127 lines (90 loc) · 5.02 KB

readme.md

File metadata and controls

127 lines (90 loc) · 5.02 KB
Raw

Development

Bibliograph is Open Source software - you are welcome to adapt it for your needs and make it better. Simply create a fork on GitHub, check it out locally and start hacking away...

Setup development environment

Prerequisites

In order to be able to develop Bibliograph with the same tools regardless of the development environment, a dockerized setup is used. You need the following prerequisites:

  • Docker - See installation instructions on https://www.docker.com On the Mac, make sure to use Docker Desktop >= v2.3.3.0, otherwise the performance of MariaDB/MySql is abysmal.

  • NodeJS, latest LTS - It is suggested to use nvm.

  • PNPM: Install with npm install -g pnpm - you can also use NPM, if you prefer.

Install frontend and backend development environment

First, run pnpm install to install all needed NPM modules.

The backend consists of the following dockerized services running in separate containers:

  • PHPFarm with php versions 7.2 - 8.0 via Apache on localhost:8072-8080
  • MariaDB on localhost:3036

If you don't need to support the whole range of PHP versions listed above, override the PHP_TEST_VERSIONS environment variable defined in test/.env by redefining it in a new file test/.env.local. This will speed up installation and testing considerably.

Installing the composer dependencies is much faster if you configure Composer with a GitHub Personal Access Token. Go to https://github.com/settings/tokens and generate a new token, then execute

tool/bin/composer config -g github-oauth.github.com <TOKEN>

Now run tool/env/install to set up the docker containers with the backend services. Finally, run

tool/env/select-php-version

This will present you with a choice of PHP versions supported by the development environment. Select the version that is running on the deployment server. You can switch the version any time by re-running the script.

Since the backend is dockerized, you need to use wrapper scripts to call the underlying basic executables, such as php, composer, codecept, or yii. They can be found in tool/bin directory.

Start the backend services and run the application

To start the services, run pnpm run services:start. Afterwards, you need to run pnpm run dev:clean to run the application in development mode for the first time, setting up the MariaDB server beforehand. If you are on a Mac, this will also open the application in a new Google Chrome window together with its developer tools.

This also starts the continuous compilation process which will update the application bundle that is loaded into the browser each time you change anything in the frontend code. You will have to reload the application to see the changes, however.

To restart the application and continous compilation without resetting the backend data, run pnpm run dev. If you want to restart the continuous compilation process without opening a browser window, use pnpm run compile:watch.

Internationalization

Using Yii2's and Qooxdoo's internationalization API, Bibliograph can easily support any language for which translation strings are supplied.

Yii2

Qooxdoo

Update dependencies

The project has the following dependencies:

To update these dependencies their latest compatible version, use pnpm run update.

After you update the npm or composer dependencies manually (or via the GitHub dependabot mechanism), run pnpm install.

Testing code changes

The PHP backend is covered by a fairly extensive test suite which can be run with pnpm runn test:codeception:all. Any changes to the backend should be checked by running this suite, and any non-trivial addition to it should come with an individual test for each new feature. You can also run unit, functional and API tests separately with pnpm run test:codeception:(unit|functional|api).

Frontend tests using Playwright are in preparation.

Deployment

See Testing and production deployment

Known issues

  • In rare cases, changed backend code isn't properly synchronized between the main file system and the docker container; this causes the Apache/PHP server to executes a previous version of the code. If you experience this, execute pnpm run services:apache:restart, which restarts Apache and will force it to use the new state (Using docker-sync might fix the problem - see to-do below).