{"id":18441595,"url":"https://github.com/stefanwalther/boilerplate-typescript-rest-docker","last_synced_at":"2025-04-07T22:32:26.273Z","repository":{"id":13127968,"uuid":"73670309","full_name":"stefanwalther/boilerplate-typescript-rest-docker","owner":"stefanwalther","description":"How to use TypeScript \u0026 Docker building a REST service with debugging enabled (e.g. WebStorm or VSCode).","archived":false,"fork":false,"pushed_at":"2025-04-01T10:34:35.000Z","size":1419,"stargazers_count":17,"open_issues_count":13,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-01T11:31:33.772Z","etag":null,"topics":["continuous-integration","continuous-testing","docker","rest","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stefanwalther.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-11-14T05:35:47.000Z","updated_at":"2024-12-02T11:58:54.000Z","dependencies_parsed_at":"2023-09-26T15:33:34.077Z","dependency_job_id":"7b376d5b-4f14-4343-88b2-17165dffeb2c","html_url":"https://github.com/stefanwalther/boilerplate-typescript-rest-docker","commit_stats":{"total_commits":22,"total_committers":4,"mean_commits":5.5,"dds":"0.13636363636363635","last_synced_commit":"b427dd7259bc395aba9fb77afca9c8bd8a8eb360"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanwalther%2Fboilerplate-typescript-rest-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanwalther%2Fboilerplate-typescript-rest-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanwalther%2Fboilerplate-typescript-rest-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stefanwalther%2Fboilerplate-typescript-rest-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stefanwalther","download_url":"https://codeload.github.com/stefanwalther/boilerplate-typescript-rest-docker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247741489,"owners_count":20988412,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["continuous-integration","continuous-testing","docker","rest","typescript"],"created_at":"2024-11-06T06:38:42.281Z","updated_at":"2025-04-07T22:32:21.902Z","avatar_url":"https://github.com/stefanwalther.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# boilerplate-typescript-rest-docker [![Build Status](https://travis-ci.org/stefanwalther/boilerplate-typescript-rest-docker.svg?branch=master)](https://travis-ci.org/stefanwalther/boilerplate-typescript-rest-docker)\n\n\u003e How to use TypeScript \u0026 Docker building a REST service with debugging enabled (e.g. WebStorm or VSCode).\n\n## Installation\n\n```sh\n# Clone the directory\n$ git clone https://github.com/stefanwalther/boilerplate-typescript-rest-docker\n\n# Install the local dependencies\n# - Not necessary if you just want to use/test the docker containers\n\n$ npm install\n```\n\n## The Development Workflow\n\nThe development environment contains the following:  \n\n- A docker container called `rest-service` containing the REST server as defined in `./src`.  \n- The REST services is exposed at `http://localhost:8000`.  \n- Watcher (using [nodemon]()http://nodemon.io/ ): As soon as you make changes to the `./src` folder, the TypeScript files will be transpiled again and the server restarted.\n  - So you can run your integration tests against your local `rest-service` container, which is after any change immediately up to date.\n- Remote debugging enabled through port `5858`.  \n\n## Run the Development Environment\n\n```sh\n$ docker-compose --f=./docker/docker-compose.dev.yml up\n```\n\nThis will give you all of the above described.\n\n## Debugging in WebStorm\n\nAssuming that rest-service itself could rely on other services it makes sense just to spin up the development environment:\n\n```sh\n$ docker-compose --f=./docker/docker-compose.dev.yml up\n```\n\nSo you can run your integration tests against http://localhost8000\nThe `rest-service` will be updated every time you make updates to the `./src` folder.\n\nIf you want to debug the rest-service (e.g. when hitting integration tests against the `rest-service`) this is the configuration being used in this example:\n\n*Create a remote debugger* \n\n- `./docker/docker-compose.dev.yml` opens the port `5858` for the debugger, so let's connect to it:\n\n![Remote Debugger Configuration in WebStorm](./docs/images/remote-debugger-configuraton.png)\n\n### Running Unit Tests\n\nRunning the unit test in this scenario is straight-forward, just configure WebStorm as follows.\n(This will not use the container, just directly test the transpiled TypeScript code).\n\n![Configure Unit Tests in WebStorm](./docs/images/config-unit-tests.png)\n\nMost of the settings should be default, except:\n\n- *Extra mocha options:* `--require ./test/mocha.conf.js`\n- *Test file patterns:* `./test/unit/**/*.spec.ts`\n\n### Hit the Debugger (That's the trick!!!)\n\nIf you want to debug the `rest-service` (running inside the container), follow these steps:\n\n**1) Set up the remote debugger as shown above**  \n**2) Run the development environment** \n`docker-compose --f=./docker/docker-compose.dev.yml up`\n  \n**3) Set up the integration tests in Mocha:**  \n\nThe configuration is very similar to the unit tests:\n\n![Configure Integration Tests in WebStorm](./docs/images/config-integration-tests.png)\n\n- *Extra mocha options:* `--require ./test/mocha.conf.js`\n- *Test file patterns:* `./test/integration/**/*.spec.ts`\n\n**4) Start your \"Remote Debugger\"**\n\n![Start Remote Debugger in WebStorm](./docs/images/start-remote-debugger.png)\n\nHere come the trick. If you don't see your `./*.ts` files (as in the screenshot below), then the sourcemaps as created by `tsc` have not been resolved by WebStorm. (That's a bug and I'll file it as such).\n\n![Watch the Tool's Panel in WebStorm](./docs/images/toolbar-watch-1.png)\n\nThere's a neat trick, though a bit annoying, but i works:\n\nJust press the \"Re-Run Debugger\" icon, and then you should see the `./*.ts` files as in the second following screenshot.\n\n![Watch the Tool's Panel  in WebStorm](./docs/images/toolbar-watch-2.png)\n\n\n![Watch the Tool's Panel  in WebStorm](./docs/images/toolbar-watch-3.png)\n\nOnce this works you can hit any breakpoint in the `rest-service` (e.g. by running `test:integration` in `Run` mode) and it will be hit:\n\n\n![Debugging WebStorm](./docs/images/debugging-in-webstorm.png)\n\n\n\n## Continuous Integration\n\nTo simulate the Continuous Integration script run the following\n\n```sh\n$ bash ./docker/docker-ci.sh\n```\n\nAn example how to implement CI using travis is provided, have a look at the `.travis.yml` file and the [result](https://travis-ci.org/stefanwalther/boilerplate-typescript-rest-docker/) .\n\n\n## Credits\n\nThis solutions is very much inspired by the following two articles:\n\n- https://hharnisc.github.io/2016/06/19/integration-testing-with-docker-compose.html\n- https://medium.com/@creynders/debugging-node-apps-in-docker-containers-through-webstorm-ae3f8efe554d#.mplfu74fz\n\nAnother very interesting read in that context:\n\n- https://blog.hospodarets.com/nodejs-debugging-in-chrome-devtools\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanwalther%2Fboilerplate-typescript-rest-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstefanwalther%2Fboilerplate-typescript-rest-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstefanwalther%2Fboilerplate-typescript-rest-docker/lists"}