Docker is the recommended way to setup a development machine as it has all necessary tools already installed.
docker-compose follow the instructions:
We've only tested using Linux hosts, any comments or fixes on other hosts will be appreciated.
The first time, it is necessary to create a local docker configuration file that you can personalize:
cp config/docker-settings.yml config/local-docker-settings.yml
Then, you can set up a development server using:
docker/up is a wrapper for
docker-compose, you can use any command line modificator (ie:
docker/up -d instead of
👉 We use the wrapper
docker/upbecause it automatically tries to export your user ID to the docker container. Otherwise all generated files by the php server will be owned by another user or root.
👉 This script assumes to run
docker-composewithout root privileges. Its important for the user running docker to belong to the
dockergroup. As is explained in the Post-installation steps in docker.com (just run
sudo usermod -aG docker $USERto be sure).
In any case, to ensure compatibility with the traditional
docker-compose up, all created files inside the php container will have full-writeable permissions (ie: folder 777 and files 666)
👉 You can specify a custom
docker-compose.ymlfile if necessary. Just copy it or create a new one with the name
docker-compose-local.yml, this file is listed in the
.gitignoreand won't be committed.
👉 When updating from older versions (with other configurations of the
docker-compose.ymlfile) it maybe necessary to rebuild the containers. To do that just run the same command with the modifier
At this point you should be able to point your browser to http://localhost:8081 (or whatever host name you have in your local-docker-settings.yml).
The correct URL will be shown in the docker-compose log when all preparation commands finish
We recommend not to use the
-d flag on
docker-compose to be aware of the log messages while building the container or php/server errors while browsing.
- How to use Docker
- Upgrade Goteo
- SSL configuration for development
- Mailhog: Development mail debugging
- Cron: background processes
- Debugging logs
How to use Docker
docker/up wrapper export the variable of the current user in order to match the UID of the docker user. This way we avoid permission problems while developing. For more info check this post: https://denibertovic.com/posts/handling-permissions-with-docker-volumes/
docker-compose up command executes
docker/php/init.sh script, which is equivalent as running the next commands:
docker/exec composer install docker/exec npm install docker/exec bin/console migrate install docker/exec grunt build:tmp
In general, any command used in Goteo to be executed in the docker virtual machine should use the wrapper
docker/exec as it will run the command with the proper user.
If you want to test a production environment, you can pass the shell variable
DEBUG=0 to the docker-compose command:
You can overwrite the default
local-docker-settings.yml file with the GOTEO_CONFIG_FILE environment variable:
Finally -optionally-, by running the
grunt watch command alone allows you to rebuild assets automatically while editing files. Note that assets are always recompiled when docker starts.
docker/exec grunt watch
docker/exec grunt build:tmp
Upgrades and other commands can be executed the same way:
docker/exec bin/console migrate all docker/exec bin/console toolkit project docker/exec bin/console --help
If using Git, you can upgrade to any new version of Goteo pulling the new code:
git clone email@example.com:GoteoFoundation/goteo.git git pull origin devel docker/up --rebuild
The Docker image comes with (experimental) support for SSL. However, to use it you need to:
Use a test domain supported by the certificate and configure your
/etc/hoststo point it to your machine, for example
goteo.test. Add a line to your
/etc/hostsfile like this:
127.0.0.1 localhost goteo.test www.goteo.test ca.goteo.test en.goteo.test es.goteo.test eo.test
Change the URL in your
local-docker-settings.ymlsettings file, use
localhost:8081. Something like:
# url url: main: //goteo.test:8443 assets: //goteo.test:8443 # optionally: url_lang: goteo.test:8443 ...
Configure Chrome to trust the Docker certificate in order to show the site as secure. To add the certificate to the trusted CA root store you can just do (in Ubuntu you need
sudo apt install libnss3-tools certutil -d sql:$HOME/.pki/nssdb -A -t "P,," -n "localhost" -i docker/certs/localhost.crt
Mailhog: Development mail debugging
Mailhog is an email testing tool for developers. It creates a fake smtp server that caches all messages and uses a web interface to debug them.
Goteo docker is preconfigured out of the box to use Mailhog, you just need to point your browser to the address http://localhost:8082 and view the email generated by the platform.
Some emails are sent by the cron process. Docker does not run cron by default. You can manually trigger the mailing process by executing the command:
docker/exec bin/console mailing last -u
Cron: background processes
Goteo uses some background processes to certain task. For instance, sending newsletters, emails to several users, control project statuses daily or process payment refunds.
For developing is usually interesting to trigger this events manually, you can execute cron in a terminal with this command:
docker/exec bin/console cron
All pending tasks will be executed.
Some actions need geolocation services. Docker uses a container with the Maxmind Geolite2 database configured.
This databases are updated every time docker starts. If for some reason you want to update them manually, just run:
docker-compose up geoip
Goteo, by default, generates Logs in JSON format. This is convenient for machine processing but it may be a little confusing. The Docker image comes with the jq parser program installed.
You can filter some logs and prettify them by doing thinks like:
Enter into the container:
Once inside, use
grep for fitering:
tail -n100 var/logs/app_real.log | grep INFO | jq tail -f var/logs/app_real.log | grep -v DEBUG | jq
You can run test by using the wrapper
docker/test. Arguments are the same as phpunit.
It is recommended to create a test file the first time.
cp config/local-docker-settings.yml config/test-docker-settings.yml
Edit the database setting, and put
goteo_test in it:
# Database stuff db: driver: mysql # Database driver (mysql) host: mariadb # Database host port: 3306 # Database port charset: utf8mb4 # Database charset database: goteo_test # Database schema (database name) username: goteo # Database user for the goteo database password: goteo # Password for the goteo database
Then, create the database and grant permissions in the mariadb container:
docker-compose exec mariadb mysql -uroot -pcrowdfunding -e 'CREATE DATABASE goteo_test;' docker-compose exec mariadb mysql -uroot -pcrowdfunding -e "GRANT ALL PRIVILEGES ON goteo_test.* TO 'goteo'@'%';"
Finally, install the database:
GOTEO_CONFIG_FILE='config/test-docker-settings.yml' docker/exec bin/console migrate install
From now on, just run tests as:
docker/test tests/Goteo/Core/ModelTest.php docker/test tests/ ...