TheDude
/
openproject
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[chore] amended readme for docker dev env

Browse Source
pull/10433/head
Eric Schubert 3 years ago
parent 979129f52c
commit 5f3da0896a
No known key found for this signature in database
GPG Key ID: 1D346C019BD4BAA2
1 changed files with 43 additions and 42 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 85
      docs/development/development-environment-docker/README.md

85
docs/development/development-environment-docker/README.md
Unescape View File

@ -35,7 +35,8 @@ More details and options follow in the next section.
<div class="alert alert-info" role="alert">
docker-compose needs access to at least 4GB of RAM. E.g. for Mac, this requires to [increase the default limit of the virtualized host.](https://docs.docker.com/docker-for-mac/)
docker-compose needs access to at least 4GB of RAM. E.g. for Mac, this requires
to [increase the default limit of the virtualized host.](https://docs.docker.com/docker-for-mac/)
Signs of lacking memory include an "Exit status 137" in the frontend container.
@ -96,42 +97,51 @@ To see the backend logs as well, use
bin/compose up frontend backend
```
This starts only the frontend and backend containers and their dependencies. This excludes the testing containers, which
are harmless to start as well, but take up system resources and clog your logs while running.
This starts only the frontend and backend containers and their dependencies. This excludes the workers, which are needed
to execute certain background actions. Nevertheless, for most interactions the worker jobs are not needed. If needed,
the workers can be started with the following command. Be aware that those process will consume a lot of the system's
resources.
This process can take quite a long time on the first run where all gems are installed for the first time.
However, these are cached in a docker volume. Meaning that from the 2nd run onwards it will start a lot quicker.
```
bin/compose up worker
```
The testing containers are excluded as well, while they are harmless to start, but take up system resources again and
clog your logs while running.
This process can take quite a long time on the first run where all gems are installed for the first time. However, these
are cached in a docker volume. Meaning that from the 2nd run onwards it will start a lot quicker.
Wait until you see `frontend_1 | : Compiled successfully.` and `backend_1 | => Rails 6.0.2.2 application starting in development http://0.0.0.0:3000` in the logs.
This means both frontend and backend have come up successfully.
You can now access OpenProject under http://localhost:3000, and via the live-reloaded under http://localhost:4200.
Wait until you see `frontend_1 | : Compiled successfully.`
and `backend_1 | => Rails 6.0.2.2 application starting in development http://0.0.0.0:3000`
in the logs. This means both frontend and backend have come up successfully. You can now access OpenProject
under http://localhost:3000, and via the live-reloaded under http://localhost:4200.
Again the first request to the server can take some time too.
But subsequent requests will be a lot faster.
Again the first request to the server can take some time too. But subsequent requests will be a lot faster.
Changes you make to the code will be picked up automatically.
No need to restart the containers.
Changes you make to the code will be picked up automatically. No need to restart the containers.
## Docker
You can stop the processes via Ctrl + C. You can also run everything in the background by adding the `-d` option as in `bin/compose up -d`. In that case you'll still be able to see the logs using `docker logs` with the respective container name.
You can see the started containers using `docker ps`.
You can stop the processes via Ctrl + C. You can also run everything in the background by adding the `-d` option as
in `bin/compose up -d`. In that case you'll still be able to see the logs using `docker logs` with the respective
container name. You can see the started containers using `docker ps`.
### Volumes
There are volumes for
* the attachments (`_opdata`)
* the database (`_pgdata`)
* the bundle (rubygems) (`_bundle`)
* the tmp directory (`_tmp`)
* the test database (`_pgdata-test`)
* the test tmp directory (`_tmp-test`)
* the attachments (`_opdata`)
* the database (`_pgdata`)
* the bundle (rubygems) (`_bundle`)
* the tmp directory (`_tmp`)
* the test database (`_pgdata-test`)
* the test tmp directory (`_tmp-test`)
This means these will stay between runs even if you stop and restart the containers.
If you want to reset the data you can delete the docker volumes via `docker volume rm`.
This means these will stay between runs even if you stop and restart the containers. If you want to reset the data you
can delete the docker volumes via `docker volume rm`.
## Running tests
## Running tests
Start all linked containers and migrate the test database first:
@ -151,26 +161,20 @@ or for running a particular test
bin/compose run backend-test bundle exec rspec path/to/some_spec.rb
```
You can run specific tests too. For instance:
```
docker-compose run backend-test bundle exec rspec spec/features/work_package_show_spec.rb
```
Tests are ran within Selenium containers, on a small local Selenium grid. You can connect to the containers via VNC if
you want to see what the browsers are doing. `gvncviewer` on Linux is a good tool for this. Check out the docker-compose
file to see which port each browser container is exposed on. The password is `secret` for all.
## Local files
Running the docker images will change some of your local files in the mounted code directory.
The file `frontend/package-lock.json` may be modified.
You can just reset these changes if you want to commit something or pull the latest changes.
Running the docker images will change some of your local files in the mounted code directory. The
file `frontend/package-lock.json` may be modified. You can just reset these changes if you want to commit something or
pull the latest changes.
## Debugging
It's common to just start a debugger within ruby code using `binding.pry`.
This **does not work** with the application running as shown above.
It's common to just start a debugger within ruby code using `binding.pry`. This **does not work** with the application
running as shown above.
If you want to be able to do that, you can, however, simply run the following:
@ -178,17 +182,14 @@ If you want to be able to do that, you can, however, simply run the following:
bin/compose run
```
If the frontend container is not running yet, it will be started.
If the backend container is already running, it will be stopped.
Instead it will be started in the foreground.
This way you can debug using pry just as if you had started the server locally using `rails s`.
You can stop it simply with Ctrl + C too.
If the frontend container is not running yet, it will be started. If the backend container is already running, it will
be stopped. Instead it will be started in the foreground. This way you can debug using pry just as if you had started
the server locally using `rails s`. You can stop it simply with Ctrl + C too.
## Updates
When a dependency of the image or the base image itself is changed you may need
rebuild the image. For instance when the Ruby version is updated you may run into
an error like the following when running `bin/compose setup`:
When a dependency of the image or the base image itself is changed you may need rebuild the image. For instance when the
Ruby version is updated you may run into an error like the following when running `bin/compose setup`:
```
Your Ruby version is 2.7.4, but your Gemfile specified ~> 3.0.3

Write Preview
Loading…
Cancel
Save