{"id":28770874,"url":"https://github.com/glasskube/hello-distr","last_synced_at":"2025-10-16T23:15:48.183Z","repository":{"id":279624438,"uuid":"937960869","full_name":"glasskube/hello-distr","owner":"glasskube","description":"Example application used in the Distr tutorial","archived":false,"fork":false,"pushed_at":"2025-06-10T23:41:22.000Z","size":610,"stargazers_count":2,"open_issues_count":12,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-11T00:33:26.908Z","etag":null,"topics":["distr","docker","example","nextjs","python"],"latest_commit_sha":null,"homepage":"https://distr.sh/docs/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glasskube.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"zenodo":null}},"created_at":"2025-02-24T07:41:44.000Z","updated_at":"2025-06-10T23:39:13.000Z","dependencies_parsed_at":"2025-02-26T15:26:26.260Z","dependency_job_id":"f0c2bcc3-b31b-43a0-ad63-3b900da41f9c","html_url":"https://github.com/glasskube/hello-distr","commit_stats":null,"previous_names":["glasskube/hello-distr"],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/glasskube/hello-distr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glasskube%2Fhello-distr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glasskube%2Fhello-distr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glasskube%2Fhello-distr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glasskube%2Fhello-distr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glasskube","download_url":"https://codeload.github.com/glasskube/hello-distr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glasskube%2Fhello-distr/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260364796,"owners_count":22998004,"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":["distr","docker","example","nextjs","python"],"created_at":"2025-06-17T13:07:35.095Z","updated_at":"2025-10-16T23:15:48.171Z","avatar_url":"https://github.com/glasskube.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hello-distr\n\nThis is a web application to demonstrate the build, deployment and release workflow for applications in Distr.\nIt consists of a next.js application, a Python backend and a Postgresql database. \nThe containers are deployed via docker compose behind a Caddy reverse proxy, allowing access to the frontend and the\nPython API.\n\nFeel free to fork it, tinker around a bit and find out what Distr can offer for your on premises software. \n\n## Tools\n\nWe make use of: \n* GitHub Actions/Workflows\n* GitHub Registry (`ghcr.io`)\n* [Release Please](https://github.com/googleapis/release-please-action)\n* [`distr-create-version-action`](https://github.com/glasskube/distr-create-version-action)\n\n## Repository Structure\n\nApart from a directory for the code, config and `Dockerfile` of each the applications' components (`backend`, `frontend`, `proxy`), \nthere are the following deployment specific files/directories:\n\n* `.github/workflows/*.yaml`: These specify the GitHub action workflows.\n* `deploy/`: Contains the [production docker compose file](deploy/docker-compose.yaml) and an [environment template](deploy/env.template). \nThese will be uploaded to distr using the [`distr-create-version-action`](https://github.com/glasskube/distr-create-version-action), \nas defined in the [push-distr workflow](.github/workflows/push-distr.yaml).\n* `release-please-config.json`: Contains the config for the release please action.\n\n## How it works\n\nThe GitHub workflows behave differently in different scenarios. For example, when opening a PR after or during feature development, \nwe want the docker build to run, but of course the built image should not be published or released yet.\n\n### On Pull Request\n\nWhen opening a PR, the `build-*` jobs are run, i.e. each part of the application is built with docker. The corresponding\n`Dockerfile`s can be found inside each components' directory.\n\n### On Push to main\n\nWhen pushing to `main`, e.g. by merging a PR, the docker images are built again.\n\nAdditionally, the `release-please` workflow is run. For that to work, the corresponding GitHub action needs permissions on the repository.\nWe set a GitHub secret in this repository and give it the name `RELEASE_GITHUB_TOKEN`. \n\nFor more information about the Release Please token, please [check their docs](https://github.com/googleapis/release-please-action?tab=readme-ov-file#github-credentials).\n\n### On Push Tag (Release)\n\nOnce there is at least one commit to `main` since the last release, Release Please will open a new PR or update its existing one.\nThe changeset will mostly include version changes and adding relevant information to the `CHANGELOG`.\n\nAfter testing and making sure everything is ready to release, you can approve and merge the Release Please PR. This will\npush a tag with the new version name to the repository.\nHowever you can also push a tag by yourself – it will also start the defined workflows. \n\nThe `build-*` workflows are started again, however this time, as the triggering event is a tag push, they will also log in to\nthe GitHub registry before the build, and afterwards push the resulting images to the registry.\n\n#### Releasing a new Distr application version \n\nOn release, additionally, the [`push-distr`](.github/workflows/push-distr.yaml) workflow is started, \nwhich uploads the artifacts in `deploy/` (`docker-compose.yaml` and `env.template`)to the Distr Hub, \nand makes the new version available to you and your customers. The used version name is the pushed git Tag. \n\nThis GitHub action needs to authenticate itself against the Distr Hub, and it needs additional information as to which application the new\nversion should be added to. Therefore follow these one-time setup steps: \n* Create a Distr Personal Access Token in your account, as described [here](https://distr.sh/docs/integrations/personal-access-token/). \n* Add the Distr PAT to your GitHub repo's secrets and call it `DISTR_TOKEN`. \n* Make sure to have a Distr application in place, to which the newly released version can be attached. If the application does not exist yet,\ncreate it via the Distr Web interface, by giving it a name (like `hello-distr`) and setting the type to `docker`. \nOnce created, copy the ID of the application from the web interface (click on the left-most column in the application list).\n* Add the copied application ID as a variable to your GitHub repository and call it `DISTR_APPLICATION_ID`. Alternatively you can also \ndirectly paste it into the `push-distr.yaml` workflow file (but please never directly paste any tokens/secrets!). \n\nSee [distr-create-version-action docs](https://github.com/glasskube/distr-create-version-action/blob/main/README.md#usage) for further information regarding\nthis GitHub action. \n\nNote that in this example repo, we set the `api-base` to `https://demo.distr.sh/api/v1`. In order to make use of this in production, \nyou should remove this line to use the default Distr Hub (`app.distr.sh`) instead. \n\n### Common Requirements\n\n#### Showing the build version in the frontend\n\nWe often want to display the software's own version in the user interface. \nTo that end we can pass the version name (i.e. the git tag) to the environment of the frontend docker build, which itself\nwrites this version into a `version.json` file inside the app. The version defined in this file will then be displayed in a \nfrontend component. \n\nTo add the argument to the docker build (see `.github/workflows/build-frontend.yaml`):\n```yaml\nbuild-args: |\n  VERSION=${{ github.ref_name }}\n```\n\nTo accept this `VERSION` environment variable (see `frontend/Dockerfile`):\n```\nARG VERSION\nENV VERSION=${VERSION}\n```\n\nTo write the version file inside the frontend repo, there is the `frontend/hack/update-frontend-version.js` script:\n```javascript\nconst out = JSON.stringify({version: env['VERSION'] || 'snapshot'}, null, 2)\nawait writeFile('buildconfig/version.json', out);\n```\n\nThis script is hooked into the next.js build process as `prebuild`, see `frontend/package.json`:\n```json\n\"prebuild\": \"npm run buildconfig\",\n\"buildconfig\": \"node hack/update-frontend-version.js\"\n```\n\n### Production docker compose file and environment variables\n\nSo far we have managed to build and release a new version of `hello-distr` and to publish the deploy artifacts to Distr Hub.\nLet's now take a look at these artifacts.\n\nYou can find the production compose file at [`deploy/docker-compose.yaml`](deploy/docker-compose.yaml). For all the services to start up and run correctly,\nsome environment variables need to be passed from the outside. You or your customer (depending on the deployment environment)\nwill have to set these variables, when deploying the `hello-distr` application via the Distr web interface. \n\nIn order to make this process easier for you and your customers, you can define an optional environment template \n(see [`deploy/env.template`](deploy/env.template)) and upload it to Distr with the `template-file` parameter of the GitHub action. \n\nThis template is a simple text file with `KEY=VALUE` lines. Note: This template is only for the user to set the possible environment\nvalues when deploying the app via Distr – and it will only be shown at the **first** deployment of this app. When later updating\nto a newer version, the deploy modal in the Distr web interface will show the previously set variables, not the template!\n\nYou can use this template to set recommended values and to leave additional comments. \n\n## `hello-distr` in action\n\nOnce deployed, the `hello-distr` app will be available at port 80 of the given hostname (env variable `HELLO_DISTR_HOST`).\nThe user interface will be available at `http://\u003chostname\u003e`, and the python API will be available at `http://\u003chostname\u003e/api`. \nThe UI consists of only one page showing the deployed version and the latest entry in the `messages` table of the postgres DB. \nTo demonstrate that the API is also publicly available, you can `POST` a newer message to it:\n\n```shell\ncurl -X POST http://\u003cyour-hostname\u003e/api/messages -d '{\"text\": \"hello distr lol\"}'  -H 'Content-Type: application/json'\n```\n\nAfter refreshing the UI, it should display the newly added message. \n\n## Local Development\n\n**Postgres**\n\nYou can install Postgres locally or use Docker to run it in a container.\n\n```shell\ndocker compose up\n```\n\nTo start the backend or frontend, please consult the respective `README`s in the subdirectories. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglasskube%2Fhello-distr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglasskube%2Fhello-distr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglasskube%2Fhello-distr/lists"}