Getting Started
Before implementing a feature or fixing a bug or security issue you need to set up a development environment. The easiest way is to install Docker Desktop on your machine. If you are using windows, you need to set up WSL2 first and configure docker to use WSL.
Dev command line tool
For the development environment the same docker containers as for the production environment are used.
However, the docker-compose-dev.yml
file is optimized for development and a helper command line tool called sail
is provided.
It is a script created by Laravel to wrap common docker compose commands and has been adjusted for PILOS.
Installation
First clone the repository to your preferred directory (for Windows inside of WSL).
git clone https://github.com/THM-Health/PILOS.git
cd PILOS
Next we need to create a .env
file by copying the default .env.example
file.
cp .env.example .env
Now we should adjust the .env
file for development:
APP_ENV=local
APP_DEBUG=true
To create a new container you can use the following command:
./sail build
The www-data use inside the container should have the same user id as the user on the host system.
This allows both the host and the container to access and modify the same files.
Building the container using sail will automatically set the WWWGROUP
and WWWUSER
to the user id of the host system.
If you want to build the container directly using docker compose, you need to set the WWWGROUP
and WWWUSER
in the .env file to the user id of the host system.
You can start the application with:
./sail up -d
To adjust the port of the webserver, change APP_PORT
in the .env
file.
SSL
In case you want to use SSL, you need a domain name and a valid SSL certificate.
Place the certificate as fullchain.pem
and the key as privkey.pem
in the ssl
directory (create if not exists).
Then you need to set the following environment variables in the .env file:
APP_URL=https://your-domain.com
VITE_SSL=true
VITE_HOST=your-domain.com
The docker container will detect the certificate and key on the next start and use them for the webserver.
Install dependencies
./sail composer install
./sail npm install
Adjust config
In the .env
file you can make your necessary adjustments.
Also, it is necessary to generate a new application key with the following command:
./sail artisan key:generate
Make sure to have APP_ENV=local
during local development.
If set to production
, some caching and performance optimisation is done during the start of the container, which makes it impossible to edit the source code in real time.
Database
Using MariaDB
The development environment comes with mariadb that is preconfigured in the .env file.
Using PostgreSQL
You can also use PostgreSQL as an alternative database since PILOS v2.
To run a local PostgreSQL using docker you have to adjust the docker-compose-dev.yml
file:
db:
image: postgres:14.6-alpine3.17
container_name: postgres
restart: unless-stopped
volumes:
- postgres:/var/lib/postgresql/data
- './tests/Utils/create-postgres-testing-database.sql:/docker-entrypoint-initdb.d/10-create-testing-database.sql'
environment:
PGPASSWORD: '${DB_PASSWORD}'
POSTGRES_USER: '${DB_USERNAME}'
POSTGRES_PASSWORD: '${DB_PASSWORD}'
POSTGRES_DB: '${DB_DATABASE}'
healthcheck:
test: ["CMD-SHELL", "pg_isready"]
retries: 3
timeout: 5s
We also have to adjust the volume configuration in the docker-compose-dev.yml
:
volumes:
postgres:
driver: local
After implementing these changes the docker-container has to be restarted with:
./sail down
./sail up -d
To use a different database adjust the .env
file:
# Database config
DB_CONNECTION=pgsql
DB_HOST=db
DB_PORT=5432
Running Migrations and Seeders
You need to run the artisan command for migration and seeding. In the production setup this command is run automatically on startup.
./sail artisan migrate --seed
PHPMyAdmin
You can manage your MariaDB using PHPMyAdmin. To adjust the port of PHPMyAdmin, change FORWARD_PHPMYADMIN_PORT in the .env file. By default, PHPMyAdmin is served at http://localhost:8080
Superuser
To create a new superuser run the artisan command for superuser creation (see Getting Started)
./sail artisan users:create:superuser
LDAP
For local development the included LDAP server can be used. To use this, it must first be configured in the .env
:
# LDAP config
LDAP_ENABLED=true
LDAP_HOST=openldap
LDAP_USERNAME="cn=readonly,dc=university,dc=org"
LDAP_PASSWORD="readonly"
LDAP_PORT=389
LDAP_BASE_DN="ou=people,dc=university,dc=org"
LDAP_TIMEOUT=5
LDAP_SSL=false
LDAP_TLS=false
# LDAP logging debugging only
LDAP_LOGGING=true
# Attribute with GUID; OpenLDAP: 'entryuuid', AD: 'objectGUID'
LDAP_GUID_KEY=entryuuid
# Comma seperated list of the object class
LDAP_OBJECT_CLASSES=top,person,organizationalperson,inetorgperson
# Attribute by which the user should be found in the LDAP
LDAP_LOGIN_ATTRIBUTE=uid
Then the attribute and role mapping must be configured by creating a file in the following path app/Auth/config/ldap_mapping.json
:
{
"attributes": {
"external_id": "uid",
"first_name": "givenname",
"last_name": "sn",
"email": "mail",
"groups": "memberOf"
},
"roles": [
{
"name": "user",
"disabled": false,
"rules": [
{
"attribute": "groups",
"regex": "/^cn=students,ou=groups,dc=university,dc=org$/i"
}
]
},
{
"name": "admin",
"disabled": false,
"all": true,
"rules": [
{
"attribute": "groups",
"regex": "/^cn=staff,ou=groups,dc=university,dc=org$/i"
}
]
}
]
}
This role mapping gives users of the group students the user role and users of the group staff the admin role.
There are three user accounts (see docker/openldap/bootstrap.ldif
)
- Name: John Doe, Username: jdoe, Password: password, Groups: Student
- Name: Richard Roe, Username: rroe, Password: password, Groups: Staff
- Name: John Smith, Username: jsmi, Password: password, Groups: Student and Staff
PHPLdapAdmin
The manage your local openldap server, you can use the PHPLdapAdmin UI. To adjust the port of PHPLdapAdmin, change FORWARD_PHPLDAP_PORT in the .env file. By default PHPLdapAdmin is servered at http://localhost:6680
BigBlueButton
For testing functionality of the application which requires a running BigBlueButton server you may need to install a server on your development machine.
Finish Setup
Checkout the Administration docs for additional steps needed to finish your setup.
The production container automatically runs the pilos-cli frontend:build
command to build the frontend.
In the development environment you can build the frontend with the following command:
./sail npm run build
However, for development it is recommended to use the development server for hot reloading:
./sail npm run dev
For the development you can use any editor of your choice but please do not check in any configuration files for your editor. In this case you may want to
extend the .gitignore
with yours editor config files.