Requirements
A working installation of docker
and docker-compose
Getting started
This application comes with an example configuration for running with docker-compose
. To get started rename .env.dist
to .env
and docker-compose.yml.dist
to docker-compose.yml
and adjust both configuration files to your local needs.
The file docker-compose.yml.dist
contains a default configuration suitable for local development. To build the images and run tests:
$ ./build.sh
Now you are ready to start the containers
$ docker-compose up -d
To setup your .env
file follow the instructions given from
$ docker-compose exec php lima app:env:setup
For more information on how to manage containers, please refer to the docker-compose CLI reference
Useful commands
# Wipe database
$ docker-compose exec php lima app:db:wipe
# Run migrations
$ docker-compose exec php lima migrations:migrate
# Create a new user (any role)
$ docker-compose exec php lima app:user:create
# Create the default admin user
$ docker-compose exec php lima app:user:create --default
# Load demo data
$ docker-compose exec php lima app:db:demo-data
Enable HTTPS
The default nginx config for development contains configuration for HTTPS support. The only thing you need to do is to generate a certificate. You can use a self-signed certificate for simplicity, if you can tolerate the warnings in the browser. But there are already scripts helping you to generate a local CA certificate, which you can install in your browser or operating system.
For generating a local root CA certificate, please refer to docker/nginx/generate-root-cert.sh
. Please read the script
and verify the paths are valid for your system before running.
To generate a signed certificate for lima.local
, please check out docker/nginx/generate-site-cert.sh
.
Same rules for that script: Please have a look inside, before running it.
If you need to change paths, make your sure to reflect the changes in docker-compose.yml
and your nginx configuration.
OS users & file permissions
Configure user: 1000:1000
in docker-compose.yml
if you want to mount the project files into the container.
Error codes
In case of error the client will be supplied with a human-readable message, a specific error code (uppercase string, starting with "ERR"-) and an associated HTTP status code. A client should implement its own validation to ensure user input does not cause errors in the API.
Code | HTTP Status Code | Description |
---|---|---|
ERR-AUTHENTICATION | 401 - Unauthorized | User could not be authorized |
ERR-CONFLICT | 409 - Conflict | Request conflicts with the current state of an object |
ERR-INTERNAL | 500 - Internal Server Error | Internal error, report to developer |
ERR-INVALID-INPUT | 400 - Bad Request | Request contains invalid input values |
ERR-MAINTENANCE-MODE | 503 - Service Unavailable | Service is temporarily not available due to maintenance |
ERR-METHOD-NOT-ALLOWED | 405 - Method Not Allowed | HTTP method is not allowed for this URL |
ERR-NOT-FOUND | 404 - Not Found | Requested object could not be found in database |
ERR-PERMISSION | 403 - Forbidden | Request is not permitted to the current user |
ERR-UNIQUENESS | 400 - Bad Request | A Value violates a uniqueness constraint |
Environment variables
The following table lists the environment variables used in the application. Dynamic values are populated automatically
by the application. Static values must be supplied from the outside (e.g. by using a .env
file)
Name | Mode | Description |
---|---|---|
ADMIN_EMAIL | Static | Email address for default admin user |
ADMIN_PASSWORD | Static | Password for default admin user |
APP_HOME | Dynamic | Path to application home directory |
APP_LOGOS_PATH | Dynamic | Path to directory for logos |
APP_LOGOS_PUBLIC_PATH | Static | Public URL path to logos |
EMAIL_SENDER_ADDRESS | Static | Sender address for outbound emails |
EMAIL_SENDER_NAME | Static | Sender name for outbound emails |
EMAIL_URL | Static | URL to use for outbound emails (gateway) |
JWT_SECRET | Static | Hex-encoded secret for JSON Web Tokens |
LOG_LEVEL | Static | Minimum level for log messages |
LOG_PATH | Static | Path to log file |
MAINTENANCE_MODE | Static | Switch to toggle maintenance mode |
MYSQL_DATABASE | Static | MySQL database name |
MYSQL_HOST | Static | Hostname or IP address running MySQL |
MYSQL_PASSWORD | Static | Password for authenticating with MySQL |
MYSQL_USER | Static | Username for authenticating with MySQL |
REDIS_HOST | Static | Hostname or IP address running Redis |
Naming Conventions
Singular vs. Plural
- PHP classes: Singular
- REST resources: Plural (if resource can have multiple instances)
- DB tables: Plural
CamelCase vs. snake_case
- PHP classes: UpperCamelCase
- PHP methods and properties: lowerCamelCase
- JSON fields: snake_case
- DB tables and columns: snake_case
Domain Events
- Class name must start with a context subject like "Match" or "Team"
- Class name must contain a verb in past tense