README.md (6573B)
1 # Docker configurations 2 3 ## Folder structure 4 5 The Docker images are composed of different layers and can be used in different ways. Here is a short overview: 6 7 | Foldername | Description | 8 |----|----| 9 | `base` | A basic image containing the required php extensions to run PartKeepr. It will be generated as a starting point for any further images. | 10 | `development` | This folder contains a complete setup using docker-compose suitable for developing PartKeepr. It can be used for local unit testing and debugging. | 11 12 ## Details on the base image 13 14 The image installs a set of php extensions, composer, and configures apache to serve `/var/www/pk/web`. That is, PartKeepr should be installed in `/var/www/pk`. 15 16 This image is not ready to run but serves as a basis for the other images related to PartKeepr. 17 18 ## Details on the development installation 19 20 The docker-compose file registers multiple container services. The main PartKeepr application is called `app`. The database is a basic configuration with `mariadb:10.1` for compatibility. Third, there is a service called `initdb`. Its purpose is to restore the database and `data` folder to a pristine state. This one should normally not be used unless one wants to reset the database. 21 22 **Note:** There needs to be a useful default inserted into the initdb. At the moment it only clears out the database to be valid but containing no parts at all. Exactly the situtation you have after a fresh installation. Some test data might be useful here. 23 24 ## The main development image 25 26 Apart from some additional tools in the docker image mainly an xdebug extension for php is installed. 27 28 The image is intended to work on the main sources as checked out. This allows easy updating and testing cycles. 29 30 The local files typically belong to the developer user. This causes problems when PartKeepr does not have sufficient permissions or if the UID does not match. To overcome this, the entry point script changes the UID of the `www-data` user in the image to some UID provided by the environment variable `GITHUB_DEBUG_UID`. Any access is thus made from the same rights as the development user outside and all newly created files will belong to `www-data`. 31 32 If no explicit command is given, the service starts apache. 33 34 Before apache is started, some preparations are made. First composer is called to update any dependencies. If the user has set `PARTKEEPR_FORCE_UPDATE` to `yes`, a set of steps are run that represent a setup (see [the wiki](https://wiki.partkeepr.org/wiki/Running_PartKeepr_from_GIT#Updating)). All cron jobs are run upon restarting to avoid additional messages here. 35 36 Calling a manual command is possible as well. 37 Then, no initialation script is run and no composer run is performed. 38 Just do something like `docker-compose run --rm app composer update`. 39 40 By setting `ADD_PHPINFO_FILE` to `1`, the developer can add a file to the web folder that serves a `phpinfo()` command. 41 42 There is also a commented sketch in the docker-compose how to debug and develop the Dockerfile. 43 44 ## Setting up a development environment 45 46 In order to start using the suggested development environment a few steps are required to set them up for the first time. 47 This guide assumes, you have just freshly checked out the PartKeer repository from git. 48 49 - Navigate in a console to the folder `docker/development`. 50 - Copy the file `github.env.dist` to `github.env`. 51 - Create a github personal access token in the settings on github. You need no additional rights. Put the generated token into the file `github.env` where the `XXX...XXX` markers are. 52 - Alternatively, you can also remove the line in the `github.env` file. The reason for this setup is that github poses a rate limit on the number of accesses. When using the `composer` command much, these rate limits might be triggered easily. By logging in, the limits are pushed to higher values. 53 54 - Call `docker-compose pull` to fetch all images from the docker hub. Alternatively you could [build the images manually](#building-the-images-manually). 55 - Now you need to fire up the database and let it initialize. This is done by callng `docker-compose up -d db`. You can peek into the process by `docker-compose logs -f db`. Wait for a message that the server is ready for connections and listening on port 3306. Using `<Ctrl><c>`, you can exit from the logs. 56 - Build the `initdb` image by calling `docker-compose build initdb`. This will take a few moments as it builds a docker image. 57 By default the line `RESET_DATABASE: 'yes'` in the file `docker-compose.yml` is commented. This is to avoid accidentially removing your data. Uncomment the line. Then: 58 - Initialize the data by calling `docker-compose up initdb`. 59 - Recomment the line in the `docker-compose.yml` file you just uncommented. 60 - Now, you can fire up the main container by calling `docker-compose up -d app`. 61 - The container will initialize some dependencies. This might take some time as well. Again using `docker-compose logs -f app` you can peek into the process and with `<Ctrl><c>` you can return to the console. 62 There might be some error messages regarding missing tables. 63 - The partkeepr instance is avaliable at http://127.0.0.1:8082/. 64 - Note: If you don't set `PARTKEEPR_FORCE_UPDATE` to `yes` in the `docker-compose` file on your first run you will get a white screen as you need to start the [setup](http://127.0.0.1:8082/setup/) once. Just accept the defaults but do not create a new set of users (keep the existing ones) and select HTTP Basic authentication. 65 - You may or may or not want to set up a cron job as described. The check is disabled by default. 66 - Alternatively, you can run the cron command manually with `php app/console partkeepr:cron:run` after logging in to the container with `docker exec -it partkeepr_dev_app_1 bash`. 67 68 ## Building the images manually 69 70 It is possible to build the image manually. The main purpose is to test, debug and alter the docker setup. In order to perform the build from scratch: 71 72 - Go to `/docker/base-dev/`. 73 - Call `docker build -t partkeepr/base-dev:latest .`. You can also give another tag name but you need to adopt later. 74 - Go to `/docker/development`. 75 - Alter the `docker-compose.yml` file. 76 - Uncomment all the lines in the `app` service that start with the `build:` name as the comment indicates. 77 - You might want to alter the `SRC_IMAGE` if you tagged with a different name above. 78 - You might want to alter the name of the generated image to not overwrite the local `partkeepr/deevelopment:latest` image. 79 - Call `docker-compose build app`.