For quick and low impact changes (e.g. typos, changes to existing styling) or for a quick glance at the dashboard, you can follow this quick start section to start the frontend testing server. For all others changes, use the full setup guide.
docker-compose up frontend_testing_server watchThis will take about 10 minutes to fully install, build and compile. Once you see the watch container report that it has compiled the CSS, as shown below, then you can navigate to http://localhost:8001 and see the testing server.
watch_1 | [99] ./~/css-loader!./~/cloudgov-style/css/base.css 122 kB {0} [built]
watch_1 | + 85 hidden modules
watch_1 | Child extract-text-webpack-plugin:
watch_1 | [0] ./~/css-loader/lib/css-base.js 1.51 kB {0} [built]
watch_1 | [1] ./~/css-loader!./static_src/css/route_form.css 1.67 kB {0} [built]
After running the Full Setup instructions, you will have a local Cloud Foundry deployment (with UAA), the dashboard, mailcatcher for testing e-mails, and npm watch running so that you can automatically recompile your frontend changes.
You will need to install:
Recommendation: You should open two terminals to the root of this repository so you can run the "[Optional]" commands below so you can view more information about the containers as they start up since it does take awhile.
From the root of the repository:
# Start PCFDev.
# Will take a long time and your computer fans will spin up but afterwards
# your system will return to normal.
cf dev start -s none
# Run "cf dev start" on all subsequent runs. You can't pass configuration flags
# to an existing PCFDev deployment.
# You can only pass configuration flags on first creation.
# Create the UAA client "dashboard-local" with appropriate permissions.
# Will also delete the old one (if one exists), in case you want to try new permissions.
docker run governmentpaas/cf-uaac \
/bin/sh -c '
uaac target https://uaa.local.pcfdev.io --skip-ssl-validation && \
uaac token client get admin -s "admin-client-secret" && \
uaac client delete dashboard-local; \
uaac client add dashboard-local \
--scope="cloud_controller.admin cloud_controller.read cloud_controller.write openid scim.read scim.invite" \
--redirect_uri="http://localhost:8002/oauth2callback" \
--authorities="uaa.none scim.invite cloud_controller.admin scim.read" \
--authorized_grant_types "authorization_code client_credentials refresh_token" -s "notarealsecret"'
# Start the app. Will also take a long time
# (but not as long as the first command)
docker-compose up -d app frontend watch
# [Optional] In the second terminal, you can tail
# the logs of the containers
docker-compose logs -f
# Once the app is up at http://localhost:8002, it will be unresponsive for a few minutes until all the assets are compiled.You can navigate to three components:
| Component | Address | Description |
|---|---|---|
| The Dashboard | http://localhost:8002 | This is what this repository contains. By using PCF Dev, there are two users created automatically by default. Admin User: admin:adminRegular User: user:passWhen you login, you will need to skip the security SSL warning / add exception in your browser since we do not have a valid certificate for *local.pcfdev.io. |
| The mailcatcher view | http://localhost:8025 | Useful for debugging e-mails. There are invite flows that send e-mails. This UI captures them |
| HTML VNC Viewer | http://localhost:6901/?password=vncpassword | Useful for seeing Javascript Karma Tests and Selenium Tests running. Based on this container |
Note: the credentials here are not sensitive since they are only used with the local deployment and the credentials are public knowledge. [1] [2]
In the event that you need to modify the styling of cg-dashboard, it will most
likely occur in the cg-style repo. You can see your changes in real time by
linking and watching for the changes there.
First, have your test site up and running, e.g., with
docker-compose up -d frontend_testing_server watch. Then, start another
container to watch cg-style and rebuild on changes:
export CG_STYLE_PATH=/path/to/cg-style/repo/here
docker-compose up -d watch_cg_style
# If you're tailing the logs, you will see the `frontend` service will restart
# add the link first to cg-style (ignore the initial errors)
docker-compose exec watch bash -c "cd /cg-style && npm link && \
cd /cg-dashboard && npm link cloudgov-style && npm install"
# restart the watch service
docker-compose restart watch
# after the service comes up successfully, your local changes to cg-style will
# automatically build in the watch_cg_style service then will you will see the
# watch service automatically rebuild.In the event that you want to unlink the service, just unlink and restart watch.
docker-compose exec watch bash -c "npm unlink cloudgov-style && npm install"
docker-compose restart watchThe frontend will automatically recompile upon changing the source. That is not the case for the backend. Unfortunately, the Go watchers tried caused the CPU to spike up very high.
In order to recompile, just run:
docker-compose stop app
docker-compose up -d appIt will replace the existing app container with a new one, thus recompiling the backend.
Running one-offs is especially important if you don't have the proper tools (such as Go, node, cf cli, or uaac) installed on your computer. With Docker, you can use the appropriate executable in a container.
Format: docker-compose run --rm frontend <COMMAND>
Examples
- Add dependency:
docker-compose run --rm frontend npm install <dep> --save - Frontend unit tests:
docker-compose run --rm frontend npm run test-unit - Watch frontend unit tests:
docker-compose run --rm frontend npm run watch-test-unit - Frontend functional tests (w/o visual debugging):
docker-compose run --rm frontend npm run test-functional
For more possible commands, refer to the package.json.
Once the frontend service is up and running (via docker-compose up -d frontend), you can use the docker-compose exec command to attach to the
existing container. While viewing the container via the HTML VNC Viewer (refer
to the table above), you will see the container's Chrome browser open and
execute the commands.
Format: docker-compose exec frontend bash -c "<COMMAND>"
Examples:
- Frontend functional tests:
docker-compose exec frontend bash -c "npm run test-functional"
Currently, we need to append to the PATH at container build time, so that node
and npm are in the PATH at container runtime. Change the NODE_VERSION in the
Dockerfile in the devtools/node directory. Then rebuild the image with:
docker-compose build frontend_dev_tools
Format: docker-compose run --rm backend <COMMAND>
Examples:
- Add dependency:
docker-compose run --rm backend dep ensure -add github.com/some/repo - Run
./codecheck.sh:docker-compose run --rm backend ./codecheck.sh
If you are trying to modify your local UAA, you can use a Docker Image and use a multi-command which first logs in then runs your desired command.
Example:
docker run governmentpaas/cf-uaac \
/bin/sh -c '
uaac target https://uaa.local.pcfdev.io --skip-ssl-validation && \
uaac token client get admin -s "admin-client-secret" && \
<MORE UAA COMMAND(S)>'For an example, look at the uaac command in the Full Setup: Running
section.
Note: the credentials here are not sensitive since they are only used with PCFDEV (which is local and also the credentials are public knowledge in the PCFDEV repo).
Similar to the UAA One-Offs section, you can use a docker image with the CF CLI.
Example:
docker run governmentpaas/cf-cli \
/bin/sh -c '
cf login -a https://api.local.pcfdev.io --skip-ssl-validation -u admin -p admin && \
<MORE CF COMMAND(S)>'
Also, you could use your local CF CLI. (which you will likely have already.)
Note: the credentials here are not sensitive since they are only used with PCFDEV (which is local and also the credentials are public knowledge in the PCFDEV repo).
You can run: docker-compose down to tear down the services.
If you want to start fresh which removes ALL containers and volumes (even
those not related to the project), run ./devtools/clean.sh. It also
removes the dependencies for Go (i.e. vendor/) and Javascript (i.e.
node_modules/).
If you want to suspend PCFDev (keep all the data), run: cf dev suspend
If you want to destroy your PCDev deployment, run: cf dev destroy
In the case that there are extra files created, you should modify
devtools/node/cleanup.js so that there's a watcher that removes those files.