|
| 1 | +``` |
| 2 | + ____ __ ____ .-. |
| 3 | + / __ \____ _____ ____/ /_ ____ / / /_ .--./ / _.---., |
| 4 | + / /_/ / __ `/ ___/ ___/ __ \/ __ \/ / __/ '-, (__..-` \ |
| 5 | + / ____/ /_/ (__ |__ ) /_/ / /_/ / / /_ \ | |
| 6 | + /_/ \__,_/____/____/_,___/\____/_/\__/ `,.__. ^___.-/ |
| 7 | + `-./ .'...--` |
| 8 | + The open source password manager for teams `' |
| 9 | + (c) 2023 Passbolt SA |
| 10 | + https://www.passbolt.com |
| 11 | +``` |
| 12 | + |
| 13 | +# Setting up a working development environment using docker |
| 14 | + |
| 15 | +Please note that these instructions are for setting a functional development environment only. Refer to the [installation guide](https://help.passbolt.com/hosting/install) if you want to use Passbolt securely to share passwords with your team. |
| 16 | + |
| 17 | +## Prerequisites |
| 18 | + - [Git](https://git-scm.com/) |
| 19 | + - [Docker](https://docs.docker.com/get-docker/) v20 or newer |
| 20 | + |
| 21 | +## Preparing Local Environment |
| 22 | + |
| 23 | +1. Clone the repos |
| 24 | +Fork the Passbolt API repository. Please read [Fork a repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo?tool=webui) if you've never done this before. |
| 25 | + |
| 26 | +Clone the forked repository onto your local machine: |
| 27 | +```bash |
| 28 | +git clone git@github.com:<YOUR_FORK_HERE>/passbolt_api.git |
| 29 | +``` |
| 30 | + |
| 31 | +In addition to the Passbolt API repository, you'll also require the [passbolt_docker](https://github.com/passbolt/passbolt_docker) repository to spin up the stack using docker compose. |
| 32 | +```bash |
| 33 | +git clone https://github.com/passbolt/passbolt_docker.git |
| 34 | +``` |
| 35 | + |
| 36 | +2. Copy the initial app.php into a new one for passbolt_api (the new file will be used by the passbolt server) |
| 37 | +``` |
| 38 | +cd passbolt_api |
| 39 | +cp config/app.default.php config/app.php |
| 40 | +``` |
| 41 | + |
| 42 | +3. Run composer install to update all the dependencies. A new vendor directory will be created with all the required libraries |
| 43 | +``` |
| 44 | +cd passbolt_api |
| 45 | +docker run --rm --interactive --tty --volume $PWD:/app composer install --ignore-platform-reqs |
| 46 | +``` |
| 47 | + |
| 48 | +4. Map the passbolt.local to the localhost in the /etc/hosts |
| 49 | +``` |
| 50 | +127.0.0.1 passbolt.local |
| 51 | +``` |
| 52 | + |
| 53 | +5. Copy the .env.example file into .env and replace the PATH_TO_PASSBOLT_API variable with the path to the passbolt_api repository on your machine |
| 54 | + |
| 55 | +6. Spin-up the docker-compose containers (mariadb and passbolt server) |
| 56 | +``` |
| 57 | +cd passbolt_docker |
| 58 | +docker-compose -f dev/docker-compose-dev.yml up -d |
| 59 | +``` |
| 60 | + |
| 61 | +7. Create the first user (the administrator) by replacing the below command with your own data. More details [here](https://help.passbolt.com/hosting/install/ce/docker). |
| 62 | +``` |
| 63 | +cd passbolt_docker |
| 64 | +docker-compose -f dev/docker-compose-ce.yaml exec passbolt /bin/bash -c \ |
| 65 | + 'su -m -c "/var/www/passbolt/bin/cake passbolt register_user -u myuser@passbolt.local \ |
| 66 | + -f name -l lastname -r admin" -s /bin/sh www-data' |
| 67 | +``` |
| 68 | + |
| 69 | +8. Copy-paste the output in the browser and you are ready! |
| 70 | + |
| 71 | +# Setup xDebug |
| 72 | + |
| 73 | +In order to setup xDebug with an IDE or code editor, please use dev/Dockerfile or docker-compose/docker-compose-dev.yaml to spin up a development stack, which already contains xDebug configured to run within the Passbolt server. |
| 74 | +You will then have to configure your IDE to connect to xDebug. Below are the steps required for a few IDEs: |
| 75 | + |
| 76 | +## Visual Studio Code |
| 77 | + |
| 78 | +1. From the Extensions tab, install the "PHP Debug" extension from the "Xdebug" publisher |
| 79 | +2. In the "Run and Debug" tab, click the gear icon at the very top of the panel to "Open 'launch.json'" |
| 80 | +3. Under "configurations", add a new JSON object with the following content: |
| 81 | +``` |
| 82 | +{ |
| 83 | + "name": "Listen for Xdebug on Docker", |
| 84 | + "type": "php", |
| 85 | + "request": "launch", |
| 86 | + "port": 9003, |
| 87 | + "pathMappings": { |
| 88 | + "/var/www/passbolt": "${workspaceFolder}" |
| 89 | + } |
| 90 | +}, |
| 91 | +``` |
| 92 | +4. Check for errors by adding `xdebug_info(); die();` to the Passbolt `webroot/index.php` file and visiting the Passbolt server root page. If you don't see anything under the "Diagnosis" section, you can remove this change and start using xDebug |
| 93 | +5. In the "Run and Debug" tab, select the debug profile we added in "launch.json" ("Listen for Xdebug on Docker") and click the green arrow to connect to xDebug |
| 94 | + |
| 95 | +In case the "${workspaceFolder}" value is not mapped correctly (this seems to be the case on MacOS), you can provide the full path of the open workspace folder: |
| 96 | +* Either manually: `<ABSOLUTE_PATH_TO_WORKSPACE_FOLDER>` |
| 97 | +* Or if you store all your code fodlers in a common code place: |
| 98 | + - `<ABSOLUTE_PATH_TO_COMMON_CODE_FOLDER>/${workspaceFolderBasename}` OR |
| 99 | + - `${workspaceRoot}` (deprecated in vscode but still works, though only works in single-workspace setup) |
| 100 | + |
| 101 | +## PHPStorm |
| 102 | + |
| 103 | +1. Configure your IDE so that it can properly connect with Docker: under Settings/Preferences -> Build, Execution, Deployment -> Docker. Here is a tutorial: https://www.jetbrains.com/help/phpstorm/docker.html#enable_docker |
| 104 | +2. Then, under Settings/Preferences -> PHP -> Debug, in the "External connections" section, make sure the "Break at first line in PHP scripts" checkbox is unchecked |
| 105 | +3. Thereafter, we need to configure a PHP server, which can be done by going to File > Settings > PHP > Servers. Click on the plus sign twice to create two servers: |
| 106 | + - The first server should be set to xDebug: Name="Docker - Passbolt", Host="passbolt.local", Port="9003", Debugger="Xdebug", ProjectFiles="<PATH_TO_PASSBOLT_API_REPO>", AbsolutePath="/var/www/passbolt" |
| 107 | + - The second server should be set to the web server (passbolt.local): Name="passbolt.local", Host="passbolt.local", Port="443", Debugger="Xdebug", ProjectFiles="<PATH_TO_PASSBOLT_API_REPO>", AbsolutePath="/var/www/passbolt" |
| 108 | +4. Save and close the Settings/Preferences window |
| 109 | +5. At the top of the main window, click the "Add Configuration..." button, then "Add new..." > "PHP Remote Debug" |
| 110 | +6. Check the "Filter debug connection by IDE key", and fill in the form with: Name="Docker - Passbolt", Server="Docker - Passbolt", IDEKey="docker_passbolt" |
| 111 | +7. At the top of the main window, click the "Listen for PHP debug connection" button and start a debugging session |
| 112 | + |
| 113 | +**Note:** If you want to debug tests, you will need to properly setup the PHPUnit library under Settings/Preferences -> PHP -> Test Frameworks by adding a configuration and setting the path to phpunit.phar to "/var/www/passbolt/vendor/bin/phpunit" (the docker path mapping must be setup for it to work with this path) |
0 commit comments