{"id":28807166,"url":"https://github.com/bendahl/docker-todo","last_synced_at":"2025-12-30T21:07:17.106Z","repository":{"id":52665854,"uuid":"92436139","full_name":"bendahl/docker-todo","owner":"bendahl","description":"Simple Multi Container Docker App","archived":false,"fork":false,"pushed_at":"2022-09-13T15:53:14.000Z","size":72,"stargazers_count":3,"open_issues_count":0,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2023-08-06T13:44:40.064Z","etag":null,"topics":["docker","docker-compose","java","multi-container-docker","openapi","spring-boot"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bendahl.png","metadata":{"files":{"readme":"README.MD","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-25T19:14:30.000Z","updated_at":"2023-08-06T13:44:40.065Z","dependencies_parsed_at":"2023-01-18T06:15:20.836Z","dependency_job_id":null,"html_url":"https://github.com/bendahl/docker-todo","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/bendahl/docker-todo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendahl%2Fdocker-todo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendahl%2Fdocker-todo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendahl%2Fdocker-todo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendahl%2Fdocker-todo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bendahl","download_url":"https://codeload.github.com/bendahl/docker-todo/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bendahl%2Fdocker-todo/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260540816,"owners_count":23024895,"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":["docker","docker-compose","java","multi-container-docker","openapi","spring-boot"],"created_at":"2025-06-18T11:07:13.807Z","updated_at":"2025-12-30T21:07:17.100Z","avatar_url":"https://github.com/bendahl.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cheat Sheet\nThis cheat sheet is meant to provide a high level overview of the project and help you to get started with the Docker \nexamples provided.\n\n## Motivation\nThis project aims to provide a simple playground for multi container Docker projects and to serve as a starting point to \nfurther examine Docker. \n\n## Prerequisites\nThis project uses Java (11), Maven and Docker along with Docker Compose. \nYou will only need to install Java on your system if you're planning on building the applications without using Docker (for local development, etc...).\nOtherwise, the provided Dockerfiles will take care of this, by using [multistage builds](https://docs.docker.com/develop/develop-images/multistage-build/).\nIf you're not using Maven, don't worry, simply \nuse one of the wrapper scripts (mvnw*) in order to build the project. For all other dependencies you'll find links that \nwill provide further information here:\n\n* Docker: https://docs.docker.com/engine/installation/\n* Docker Compose: https://docs.docker.com/compose/install/\n* Java [optional]: https://www.oracle.com/technetwork/java/javase/downloads/jdk11-downloads-5066655.html\n\n__IMPORTANT__: If you're working on Linux, do not simply install Docker and Docker Compose straight from your distro's \nrepositories, as the versions found there may be outdated. Make sure to check the version first. All examples were \ncreated and tested using Version 1.13 of Docker and Docker Compose. So anything \u003e= Version 1.13 should be ok.\n\n## Project Structure\nThe below tree shows the basic project file structure and gives a few hints on what you will find where. Use this as your \nmap. More details are explained further on in the document.\n\n    .\n    ├── backend                                                     // the backend service project root\n    │   ├── Dockerfile                                              // this Dockerfile will build an image for the backend - note that you'll need to perform a Maven build first\n    │   ├── mvnw                                                    // Maven wrapper script for Mac/Linux/Cygwin\n    │   ├── mvnw.cmd                                                // Maven wrapper script for Windows\n    │   ├── pom.xml                                                 // Maven pom.xml with the basic build settings\n    │   └── src                                                     // Java sources\n    │       ├── main\n    │       │   ├── java\n    │       │   │   └── de\n    │       │   │       └── bendahl\n    │       │   │           ├── SwaggerConfig.java                  // Swagger setup (for more information see: http://swagger.io/)\n    │       │   │           ├── TodoApplication.java                // the main entry point of the app\n    │       │   │           ├── TodoEndpoint.java                   // REST endpoint\n    │       │   │           ├── Todo.java                           // the Todo entity class for DB and JSON mapping\n    │       │   │           └── TodoRepository.java                 // Spring JPA repository that handles data access\n    │       │   └── resources                                       // non-code resources used by the backend project\n    │       │       ├── application.properties                      // app settings\n    │       │       └── data.sql                                    // initial data to populate the in H2 DB\n    │       └── test\n    │           └── java\n    │               └── de\n    │                   └── bendahl\n    │                       └── TodoApplicationTests.java           // standard unit test generated by Spring Boot\n    ├── docker-compose.yml                                          // basic docker-compose file that will deploy frontend and backend, using the Docker Hub repositories\n    ├── frontend                                                    // the frontend service project root\n    │   ├── Dockerfile                                              // this Dockerfile will build an image for the frontend - note that you'll need to perform a Maven build first \n    │   ├── mvnw                                                    // Maven wrapper script for Mac/Linux/Cygwin\n    │   ├── mvnw.cmd                                                // Maven wrapper script for Windows\n    │   ├── pom.xml                                                 // Maven pom.xml with the basic build settings\n    │   └── src                                                     // Java sources\n    │       ├── main\n    │       │   ├── java\n    │       │   │   └── de\n    │       │   │       └── bendahl\n    │       │   │           ├── DemoFrontendApplication.java        // Main entry point of the frontend application\n    │       │   │           ├── TodoChangeListener.java             // interface used to create a change event binding \n    │       │   │           ├── Todo.java                           // todo class that maps to and from JSON\n    │       │   │           ├── TodoLayout.java                     // layout that is used to display the todo list items\n    │       │   │           ├── TodoList.java                       // controls the behavior of the actual todo list\n    │       │   │           ├── TodoService.java                    // the service that handles all backend calls\n    │       │   │           └── TodoUI.java                         // setup of basic layout and components of the application\n    │       │   └── resources\n    │       │       ├── application.properties                      // app settings - the backend URL is setup here\n    │       │       ├── static                                      // not needed in this case - generated by Spring Boot\n    │       │       └── templates                                   // not needed in this case - generated by Spring Boot\n    │       └── test\n    │           └── java\n    │               └── de\n    │                   └── bendahl\n    │                       └── DemoFrontendApplicationTests.java   // standard unit test generated by Spring Boot\n    └── README.MD                                                   // Start here ;-)\n\n\n### The Backend\nThe backend consists of a REST service that is built on top of Spring Boot. OpenAPI is integrated in the service in order\n to make it easy to play around with a few simple requests and get a feel for what it actually does. Besides Java and Spring \n Boot, H2 DB is used as a data store in order to keep things simple and not require an addtional database(container) to be set up.\nThe backend listens on port 8081 and the base URL is: _http://HOSTNAME_GOES_HERE:8081/todos_. The swagger web ui is located \nat: _http://HOSTNAME_GOES_HERE:8081/swagger-ui.html_. The OpenApi schema is located at: _http://localhost:8081/v3/api-docs_. \nThe health status of the backend service is exposed using the Spring Boot Actuator and exposed at \n_http://localhost:8080/actuator/health_.\n\nNote that the H2 DB is set up to use file storage, in order to be able to use this project to not only demonstrate \nnetworking in Docker, but also some storage basics. As long as the backend container is not removed, the data will not \nbe lost upon container restart/stop. The default storage location of the db is the file `/tmp/todo.mv.db` within the \ncontainer (see application.properties for details). This should be a sensible default in most cases. If, however, you \nwish to override this behavior, it's as simple as setting the environment variable `DB_FILENAME` in order to change it. \nThe format of the filename is `\u003cpath\u003e/\u003cfilename\u003e`, where filename will automatically be expanded to \"filename.mv.db\".\n\nBuilding the Docker image:\n* cd into the backend directory first \n* then enter the following (omitting the \":1.0\" will create an image tagged as \"latest\"):\n    `docker build -t todo-backend:1.0 .`\n \nCreating and running a container based on your local image:\n`docker run -d --name backend -p 8081:8081 todo-backend:1.0`\n\nThis will essentially create and immediately start a new container named \"backend\" based on your local image created above. \nYou can now connect to it on the exposed port 8081. \n\n__Useful commands__:\n\n- `docker ps`: See a list of all running containers  \n\n- `docker stop [CONTAINER]`: Stop a container\n \n- `docker ps -a`: See a list of all containers (running or not) and their status\n \n- `docker rm [CONTAINER]`: Delete a container\n\n- `docker rmi [IMAGE:TAG]`: Delete an image\n\n\n### The Frontend\nThe frontend application is a basic Vaadin Todo app, largely taken from https://github.com/vaadin-marcus/spring-boot-todo/. \nIt also uses Java, Spring Boot and Maven as its stack. It is exposed on port 8080 by default. Simply navigate to the url\n_http://HOSTNAME_GOES_HERE:8080_ in your favorite browser to see the web ui. \n\nIn order to successfully run the frontend, make sure that the backend is up and running and listening for connections\non port 8081 (default setting of the backend). You will also need to specify the environment variable _BACKEND_HOSTNAME_, \nsince the frontend uses this variable to retrieve the actual host name of the backend application.\n \nAdditional information:\nWhen using Docker, a container's host name usually matches its name. Therefore, if you started the backend container like\ndescribed above, its host name will be \"backend\". Also note that the two containers will have to be on the same bridge \nnetwork or, alternatively, use the host network (not recommended) in order to communicate with each other. All in all this\ncan be achieved in three easy steps, described in the following section.\n\n__Running frontend and backend (not using docker-compose)__:\n\n- Create a bridge network (called 'matrix' in this example): `docker network create matrix`\n- Run the backend container: `docker run -d --name backend --network matrix todo-backend:1.0 backend/.`\n- Run the frontend container: `docker run -d --name frontend --network matrix -p 80:8080 -e BACKEND_HOSTNAME=backend todo-frontend:1.0 frontend/.`\n\nThis will essentially create a new bridge network called 'matrix' and connect two containers (frontend and backend) to it.\nSince both containers are on the same bridge network, they will be able to reach each other over tcp. Therefore there is \nno need to expose any port for the backend. The frontend, on the other hand, will need to be reachable from the host network, \nso you can navigate to the web ui using your browser. That's the reason for the '-p 80:8080' in the frontend call above.\nAlso, don't forget to set the environment variable _BACKEND_HOSTNAME_ when running the frontend. Otherwise the service \nwill fail to startup, since it doesn't know the backend's host name.  \n\n__Useful commands__:\n\n- `docker ps`: See a list of all running containers  \n\n- `docker stop [CONTAINER]`: Stop a container\n \n- `docker ps -a`: See a list of all containers (running or not) and their status\n \n- `docker rm [CONTAINER]`: Delete a container\n\n- `docker rmi [IMAGE:TAG]`: Delete an image\n\n- `docker network create [NETWORK]`: Create a new network\n\n- `docker network ls`: List existing networks\n\n- `docker network rm [NETWORK]`: Delete existing network\n\n\n### Docker Compose File\nIf you wold like to run the full example (front- and backend) without going through the hassle of creating your own network\nand manually running the containers, you may also use docker-compose to automate the whole process, including the creation\nof the two images. Note, however, that you will need to successfully build the two jar files (frontend and backend) first \nin order to build the images. \n\n__Running the examples via docker-compose__:\n\n- Build the backend: `cd backend \u0026\u0026 mvn clean install \u0026\u0026 cd ..`\n- Build the frontend: `cd frontend \u0026\u0026 mvn clean install \u0026\u0026 cd ..`\n- Now run the example using docker-compose: `docker-compose up -d` (the -d ensures that the processes run in the background)\n- Open up http://localhost in your favorite browser to see the result  \n\n**NOTE THAT THIS WILL FAIL WHEN USING ROOTLESS DOCKER, SINCE PORT 80 IS A PRIVILEGED PORT. EITHER USE ANOTHER PORT IN THE COMPOSE FILE OR USE DOCKER WITH ROOT.**\n\n__Useful commands__:\n- `docker-compose up`: Run containers according to the docker-compose.yml. Stdout will be forwarded.\n- `docker-compose up -d`: Run containers according to the docker-compose.yml. Processes will be run in the background.\n- `docker-compose ps`: View running containers and their status.\n- `docker-compose stop`: Stop the running containers.\n- `docker-compose down`: Stop and delete the running containers and the newly created network.\n\n## Credits\nSpecial thanks goes to Marcus Hellberg for his excellent Vaadin example that really did prove to be a great time saver when creating the frontend application. The original \nVaadin project is located here on Github at: https://github.com/vaadin-marcus/spring-boot-todo/\n\n## Miscellaneous\nI hope that this little project will be useful for you in your quest to learn more about Docker and hopefully provide a fun playground to get started with multi container apps.\nLet me know if you've got any further ideas/suggestions! Feel free to clone the heck out of this repo and reuse whatever part you want. Cheers!","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbendahl%2Fdocker-todo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbendahl%2Fdocker-todo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbendahl%2Fdocker-todo/lists"}