Skip to content

local-docker.md

Latest commit

 

History

History
167 lines (107 loc) · 7.57 KB

local-docker.md

File metadata and controls

167 lines (107 loc) · 7.57 KB

Running Narrative in local Docker

It is useful to run the Narrative within a local docker container. E.g. this makes it easy to work on Narrative ui locally integrated with a local instance of kbase-ui.

Narrative

The following changes are required:

  • Build the docker image using the make target "dev_image", this builds the docker image without the "npm run minify" step. The image will be tagged kbase/narrative:dev instead of the current git branch

    make dev-image

  • start the container:

    ENV={ci/next/prod} [PORT=<some port number>] make run-dev-image

    where:

    - `ENV` sets the `CONFIG_ENV` environment variable for the Docker container; ci is the environment in which you are working (needs to be same as the ui is running on.)
- `PORT` sets the host port that can be used. E.g. if you use PORT=12345, then http://localhost:12345 will start the Narrative. Default is 8888.
  - Note that the logging on the console will always show 8888 since that will be used internal to the container.
- uses the config set in `$ENV`; makes it easy to test different environments alongside ui
- uses `kbase-dev` network; allows interoperation with the kbase-ui proxier to access local services
- uses container host name "narrative"
- mounts `kbase-extension/static/kbase` directory inside container; allows editing files on host and having changes reflected with a Narrative reload
- removes container when done; easy cleanup
- uses "dev" tagged container; matches the docker build task above

Integration Tests

Integration tests with Narrative running within a container are essentially the same as running on localhost, we just need an extra option:

KBASE_TEST_TOKEN=YOUR_TOKEN_HERE BASE_URL=https://ci.kbase.us make test-integration

E.g.

SERVICE=selenium-standalone BROWSER=chrome HEADLESS=f BASE_URL=https://ci.kbase.us KBASE_TEST_TOKEN=TOKEN_HERE make test-integration

The BASE_URL option will override the default test runner behavior, which is to launch a local narrative instance.

This will launch the integration test runner against the CI environment, using chrome browser, and using the chromedriver testing service.

This may all be overridden.

Additional Options

The default test configuration may be overridden with the usage of environment variables:

  • ENV indicates the deployment environment, either ci, next, narrative-dev, or prod. Additional values may be used, but if they are not supported in all the tests, the tests will fail. Defaults to ci.
  • SERVICE indicates the testing service. Currently supported services are chromedriver and selenium-standalone; defaults to chromedriver.
  • SERVICE_USER for a remote service this provides the user account id
  • SERVICE_KEY for a remote service this indicates the authorization key for using the account
  • BROWSER indicates the browser to test against; chrome and firefox are supported; defaults to chrome
  • HEADLESS indicates that the browser should be run in headless mode; may be t or f; defaults to t

Testing Scenarios

default local test

This is the default, documented integration test method:

make test-integration
  • by default the default environment is ci, the default browser is chrome, and the default testing service is chromedriver.
  • Note that this requires a local build, which you should have already conducted.
  • starts up a narrative server on your host, in python
  • if testing is interrupted, the port may be retained by the process, you should be prepared to run lsof -i -n -P | grep 32323 where 32323 is the default port
    • the symptom for this will be an error message when attempting to run the tests.

All of the testing options may be used

ci local container

narrative-dev local container

next local container

prod local container

Notes

The container can't be killed with Ctrl-C; you'll need to stop it using Docker or another tool like Kitematic.

If you need to update or change dependencies (package.json), you'll need to rebuild the image.

config.json changes

The Dockerfile runs src/scripts/kb-update-config to generate /kb/deployment/ui-common/narrative_version. This script has the unfortunate side effect of overwriting the config file source in /src/config.json. This is a little frustrating because it means that a committer has to be very careful to omit this file when building the image for development or testing.

kbase-ui

The kbase-ui development proxy knows how to route to a local narrative container. To invoke this behavior add local-narrative=t to the start line as run from the kbase-ui repo:

make start env=ci build=dev build-image=f local-narrative=t

Use build-image=t if you haven't built the kbase-ui image yet.

Running against another environment

For testing against other KBase deployment environments, you can change the option env to next, narrative-dev, or prod. The Narrative will need to be restarted to point to that environment.

In the narratives repo:

ENV=next make run-dev-image

In the kbase-ui repo:

make start build-image=f env=next local-narrative=t

Note that the integration tests do not directly support running against environments other than CI, due to the need to set up test narratives in each environment, and to pass an environment variable indicating which environment dataset to switch to.

Done

You should now be able to navigate to https://ci.kbase.us, log in, and pull a Narrative from the Dashboard.

Testing with a local container

Testing instructions assume that JS and Python dependencies are installed locally, and that the Narrative is built on the host for local usage.

Recent changes introduce running the Narrative via a Docker container

This, however, is not necessary with the container, although it is still necessary (for now) to install JS dependencies because tooling relies up it. Of course, it would be possible to run any node-based tool via a simple node container, but that is for another day.

  • Get the narrative running in one terminal window:

    • make dev-image
    • ENV=ci make run-dev-image

  • Ensure node testing dependencies are installed:

    • npm install

  • In another terminal window:

    • NARRATIVE_SERVER_URL=http://localhost:8888 npm run test_local if running w/o kbase-ui
    • NARRATIVE_SERVER_URL=https://ci.kbase.us/narrative npm run test_local, optionally if running with kbase-ui proxying ci.

NOTE: this no longer works, due to changes in the test scripts. So just use make test-frontend-unit, making sure that ci.base.us is no longer routed to 127.0.0.1 in /etc/hosts.

Please note the volume mounts in scripts/local-dev-run.sh. Not all directories in kbase-extension/static local narrative repo are mounted, due to the fact that ext_components is installed.

To explain the ext_ directories briefly.

  • ext_modules is where all node modules should be placed; that is what it was originally designed for and a very few npm dependencies are placed there; it does not exist until the narrative is built.
  • ext_components is where node_modules is copied to, for those bower components which were migrated to npm modules; it also does not exist until the narrative is built.
  • ext_packages is where old dependencies which cannot be brought into the codebase as normal npm dependencies reside; it essentially never changes as it freezes certain dependencies that could not be brought in as bower dependencies when the narrative was converted from manually installed dependencies to bower.