Skip to content

Latest commit

 

History

History
118 lines (76 loc) · 5.93 KB

README.md

File metadata and controls

118 lines (76 loc) · 5.93 KB

Docker development environment for TaxonWorks

Quick start

You can quickly start developing or testing against the API with minimal configuration. The following assumes you have Docker and its dependencies installed and running, and, presently, an up to date version of Nodejs.

  • If using MacOS/OSX Install XCode tools
  • git clone https://github.com/SpeciesFileGroup/taxonworks.git - to clone repository in directory of your choice
  • cd taxonworks
  • docker-compose build
  • docker-compose up
  • browse to 127.0.0.1:3000 if you can see something similar to below in your terminal window: 
    webpack_1  | webpack: Compiled successfully.
  • You should see the logon window.
  • Wait for a while if the logon window does not load not load quickly.
  • Use ctrl-c or docker-compose down in another local terminal to shutdown

Next steps

Develop!

Overview

  • Commands in following sections assume you are running docker-compose up in another terminal.
  • To make changes simply edit the TaxonWorks source that you cloned into your local directory
  • Changes are automatically applied and visible in the browser as they would be for the native environment.
  • In most cases you need not restart the server or redo docker-compose up to see your changes, though there are some cases in which you will.

More on Docker

  • In TaxonWorks docker-compose is configured to use Dockerfile.development
  • The container is mapped to the source on your local machine, what you see when you shell into the app is what is on your local file system.
  • See documentation for Docker.

Use a debugger like byebug or pry

Two steps. Run docker-compose in daemon mode, then attach to the app. Server log/debugger entry point will appear in the window after requests.

  • docker-compose up -d (If you are already running docker-compose up stop it first)
  • docker attach taxonworks_app_1 (Container name can be found with docker ps, but if app is running on taxonworks directory taxonworks_app_1 is likely correct)

Stop a container

Get the container id from docker ps

  • docker stop 3dc4293eg17e

Database

The database persists across use (e.g. docker builds, up/down). By default it is not the same as database described in the "native" environment approach.

TODO: move below to unified HOW TO in taxonworks_doc_

Drop and recreate the database to an empty state

  • Ensure the app is not running (you may stop it with docker-compose stop app), the database container needs to be running.
  • docker-compose exec db psql -U postgres
  • drop database taxonworks_development;
  • create database taxonworks_development;
  • \q
  • You may restart taxonworks now with docker-compose start app

Restore a database dump

Assumes you have a prior export generated by rake tw:db:dump

  • Drop and recreate the database to an empty state
  • docker-compose exec db -T pg_restore -U postgres -d taxonworks_development < /path/to/pg_dump.dump
  • Depending on when the database was dumped restore errors about roles can be ignored, i.e. the process will "fail" but be successful.
  • You may restart taxonworks now with docker-compose start app

Troubleshooting

docker & docker-compose show permission errors (Linux users)

To fix this you may follow Post-installation steps for Linux, or use sudo on docker and docker-compose commands.

"docker-compose build" fails

With a missmatched Ruby version

  • Ensure your ruby -v version matches the version in the Gemfile. You may need to update or install a new Ruby.

docker-compose build fails after RUN apt-add-repository ppa:brightbox/ruby-ng

  • Problem: It seems that sometimes the repository list update fails because of bad(?) internet connection. Difficult to replicate.
  • Solution: Do nothing, just re-run docker-compose build again.

"docker-compose up" fails

Migration related error

  • Problem: Active Migration related error is observed in client browser after following installation process.
  • Solution: The problem is patched in latest version, if you're still observing it after updating local TaxonWorks repository, re-open this issue with your problem.

With PG::ConnectionBad: could not connect to server

  • Problem: Likely you have config/database.yml already set up for your native local server or some other location that is not available
  • Solution: You can remove config/database.yml and let the startup process reconstruct it or make sure config for development environment is the same as config/database.yml.docker.compose.example

With "A server is already running"

  • If an app container is not shut down correctly (docker-compose down) it can leave the file tmp/server.pid
  • On the local file system check to see if /app/tmp/pids/server.pid exists, if it does, delete it.

With (Bundler::GemNotFound) or Log reports Gem not found

  • Bring down the containers docker-compose down
  • Redo the build step docker-compose build

Windows related

  • You may need to use localhost rather than 0.0.0.0 where applicable in database calls.

Cleanup old containers

  • Try docker images and docker rmi <id> to cleanup old images.