{"id":26562636,"url":"https://github.com/kat-kel/full-stack-container-example","last_synced_at":"2026-04-08T16:31:23.970Z","repository":{"id":282452338,"uuid":"948646955","full_name":"kat-kel/full-stack-container-example","owner":"kat-kel","description":"Docker container of a full-stack web application.","archived":false,"fork":false,"pushed_at":"2025-03-20T22:33:44.000Z","size":1802,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-22T15:18:22.080Z","etag":null,"topics":["docker","docker-compose","fastapi","fullstack","nextjs","python","tailwindcss","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/kat-kel.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-14T17:46:41.000Z","updated_at":"2025-03-20T22:33:47.000Z","dependencies_parsed_at":"2025-03-14T18:44:08.866Z","dependency_job_id":"6a0f1e2e-0269-48cf-ae70-63e9e9811c20","html_url":"https://github.com/kat-kel/full-stack-container-example","commit_stats":null,"previous_names":["kat-kel/full-stack-container-example"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kat-kel/full-stack-container-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kat-kel%2Ffull-stack-container-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kat-kel%2Ffull-stack-container-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kat-kel%2Ffull-stack-container-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kat-kel%2Ffull-stack-container-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kat-kel","download_url":"https://codeload.github.com/kat-kel/full-stack-container-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kat-kel%2Ffull-stack-container-example/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31564818,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","fastapi","fullstack","nextjs","python","tailwindcss","typescript"],"created_at":"2025-03-22T15:18:26.601Z","updated_at":"2026-04-08T16:31:23.950Z","avatar_url":"https://github.com/kat-kel.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Containerized Full-Stack Example\n\nThis is a basic example of how to structure\na (very simple) full-stack web application\nand (more to the point) set up the docker\nfiles to containerize it.\n\n## Table of Contents\n- [Explanation](#explanation)\n- [Installation](#installation)\n- [Usage](#usage)\n  - [How to run Docker containers](#use-1-docker-containers)\n  - [Code templates](#use-2-backend--frontend)\n    - [Building backend with `FastAPI`](#backend)\n    - [Building frontend with `React`](#frontend)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Explanation\n\nWhy would I use this example?\n\n- You have data that you need people to be able to access. For the more technical users, you can simply set up an API (see [`backend/`](./backend/)), deploy it, and let the technical users call the API. For a more general audience, you'll want to set up a web interface (see [`frontend/`](./frontend/)) that communicates with your API based on user-friendly queries, page navigation, user input, etc. The latter requires both the backend and frontend, aka a \"full-stack\" web application.\n\n- You need to deploy your full-stack web application from a remote server and/or you want people to be able to download it and create their own deployments. This is best managed with a \"container,\" which builds all the necessary dependencies, environment variables, etc. for software written in any programming language into a convenient package. In this example, we use `Docker` to create these containers.\n\nThis example models 3 things:\n\n1. A `FastAPI` [backend](./backend/) written in `Python`.\n\n2. A `React` [frontend](./frontend/) written in `TypeScript` and using `NextJS`.\n\n3. `Docker` files for building both ends and the whole, full-stack application.\n\n    1. Backend blueprint: [`backend/Dockerfile`](./backend/Dockerfile)\n\n    2. Frontend blueprint: [`frontend/Dockerfile`](./frontend/Dockerfile)\n\n    3. Full-stack blueprint: [`docker-compose.yml`](./docker-compose.yml)\n\n\n## Installation\n\n### Step 1. Set up Docker\n\nThe easiest way to explore this example is to download and install [`Docker Desktop`](https://www.docker.com/products/docker-desktop/), which should also install `Docker Compose` as a command-line tool.\n\n\u003e [`Docker Compose`](https://github.com/docker/compose) is licensed under Apache-2.0 (open-source), and `Docker Desktop` is free to download and use. `Docker Desktop` allows you to login with a `Docker` account, but this is not necessary.\n\n### Step 2. Download codebase\n\nDownload this example using `git clone`.\n\n\u003e If it's not already installed, first [download `git`](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).\n\n```shell\ngit clone https://github.com/kat-kel/full-stack-container-example.git\n```\n\n### Step 3. Build the containers\n\nTo build the containers, you must satisfy 2 things:\n\n1.  Make sure that `docker` is running. If you're using `Docker Desktop`, simply open the application. If `docker` is not running, you'll see the following error message when trying to build and/or run the container:\n\n```console\n$ docker compose up --build\nunable to get image 'full-stack-container-example-frontend':\nCannot connect to the Docker daemon at unix:///home/user/.docker/desktop/docker.sock.\nIs the docker daemon running?\n```\n\n2. Have your command line located at the root of this codebase, aka where the `docker-compose.yml` file is.\n\nFinally, build and begin running the full-stack app's container using `Docker Compose`.\n\n```console\n$ docker compose up --build\n[+] Running 0/0\n[+] Running 0/2tend  Building                                                   0.1s\n ⠹ Service frontend  Building                                                   0.3s\n[+] Building 60.7s (22/22) FINISHED                             docker:desktop-linux\n...\n ✔ Service frontend                              Built                         60.8s\n ✔ Service backend                               Built                          2.1s\n ✔ Network full-stack-container-example_default  Created                        0.1s\n ✔ Container client                              Created                        1.1s\n ✔ Container server                              Created                        1.1s\nAttaching to client, server\nclient  |\nclient  | \u003e frontend@0.1.0 dev\nclient  | \u003e next dev\nclient  |\nserver  |\nserver  |    FastAPI   Starting production server\n```\n\n\u003e It's normal for the build process to take serveral minutes. This example isn't designed to also show how to optimise Docker build times.\n\n## Usage\n\nThis example serves 2 main uses:\n\n1. Running and stopping `Docker` containers.\n\n2. Templates for a simple backend REST API and a simple React frontend.\n\n### Use 1: Docker containers\n\n`Docker Desktop` is the easiest way to manage running and stopping the built containers.\n\n![Screenshot of Docker Desktop and this project's container, with its two services, \"client\" and \"server.\"](./img/docker-desktop-containers.png)\n\n\nAlternatively, can run both containers (client, server) from the root of the repository (where `docker-compose.yml` is) with the command `docker compose up` in the terminal.\n\n```console\n$ docker compose up\n[+] Running 2/0\n ✔ Container server  Created                                                    0.0s\n ✔ Container client  Created                                                    0.0s\nAttaching to client, server\nclient  |\nclient  | \u003e frontend@0.1.0 dev\nclient  | \u003e next dev\nclient  |\nserver  |\nserver  |    FastAPI   Starting production server\n```\n\nIn the same terminal from which you started the containers with `docker compose up`, stop both of them by pressing `Ctrl` and `C` together.\n\n```console\nGracefully stopping... (press Ctrl+C again to force)\n[+] Stopping 2/2\n ✔ Container server  Stopped                                                    0.4s\n ✔ Container client  Stopped                                                   10.2s\n```\n\n### Use 2: Backend / Frontend\n\n#### Backend\n\n[Go to backend.](./backend/)\n\nThe backend's REST API is built with [`FastAPI`](https://fastapi.tiangolo.com/) in `Python`.\n\nTo begin developping the template and adding your own [endpoints](https://fastapi.tiangolo.com/tutorial/path-params/), data sources, etc., you'll first need to set up a virtual `Python` environment using version 3.12 or greater. Then, install the backend as a package with `pip install -e .`.\n\nFor developping purposes, run the backend separately in your virtual environment. From inside the `backend/` directory, run the following command:\n\n```console\n$ fastapi dev src/api/main.py --port 8000\n\n   FastAPI   Starting development server 🚀\n\n             Searching for package file structure from directories with __init__.py\n             files\n             Importing from\n             /home/user/Dev/full-stack-container-example/backend/src\n\n    module   📁 api\n             ├── 🐍 __init__.py\n             └── 🐍 main.py\n\n      code   Importing the FastAPI app object from the module with the following\n             code:\n\n             from api.main import app\n\n       app   Using import string: api.main:app\n\n    server   Server started at http://127.0.0.1:8000\n    server   Documentation at http://127.0.0.1:8000/docs\n```\n\nBy running your backend app with the development server (`fastapi dev`), changes you make and save in the Python modules ([`src/api/`](./backend/src/api/)) will be applied as the application automatically reloads.\n\n#### Frontend\n\n[Go to frontend.](./frontend/)\n\n##### Installation\n\nThe frontend is built in [`React`](https://react.dev/) with a [`Next.js`](https://nextjs.org/) framework.\n\nTo begin developping the components, first install the `Node` modules. Contrary to Python, you don't need a virtual environment to do this because they're installed locally in the `fontend/` directory.\n\nIn order to install the modules, you must have the following installed globally on your system:\n\n1. [`Node.js`](https://nodejs.org/en), version 20 or greater.\n\n2. [`npm`](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm?ref=meilisearch-blog), version 10 or greater.\n\n\u003e Note: The beauty of containers / Docker is that all this stuff about packages and dependencies is handled for you! But for actually developping the thing you'll containerize, you'll need to set things up yourself.\n\nFinally, from inside the [`frontend`](./frontend/) directory, where the [`package.json`](./frontend/package.json) file is, install the frontend's `node` modules with the following command:\n\n```shell\n$ npm i\n```\n\n##### Development\n\nThis frontend template was built with the [`Next.js`](https://nextjs.org/) framework, specifically using `App Router`. [Read here](https://nextjs.org/docs/app/getting-started/project-structure) about how to structure and develop a project with this architecture.\n\n## Contributing\n\nThis example is meant to remain light-weight and minimal, showcasing primarily `Docker Compose`, `FastAPI`, and `React`. For this reason, please don't contribute enhancements that add complexity to the example.\n\nHowever, if you are installing the example and discover an error on your machine, please open an issue that describes your set-up and the problem. I also welcome your input on how to make more explicit, standardised, and/or cleaner the code in the frontend and backend.\n\n## License\n\nThis project is licensed under the [MIT License](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkat-kel%2Ffull-stack-container-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkat-kel%2Ffull-stack-container-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkat-kel%2Ffull-stack-container-example/lists"}