{"id":37087964,"url":"https://github.com/henrikje/laebel","last_synced_at":"2026-01-14T10:48:54.619Z","repository":{"id":257996161,"uuid":"863092063","full_name":"henrikje/laebel","owner":"henrikje","description":"Automatic README-style documentation site for your Docker Compose project.","archived":false,"fork":false,"pushed_at":"2024-10-29T21:28:56.000Z","size":2062,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-10-29T22:48:04.126Z","etag":null,"topics":["docker","docker-compose","documentation","readme","readme-generator"],"latest_commit_sha":null,"homepage":"","language":"Go","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/henrikje.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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":"2024-09-25T17:42:52.000Z","updated_at":"2024-10-29T21:43:27.000Z","dependencies_parsed_at":"2024-11-06T23:38:00.213Z","dependency_job_id":null,"html_url":"https://github.com/henrikje/laebel","commit_stats":null,"previous_names":["henrikje/laebel"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/henrikje/laebel","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrikje%2Flaebel","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrikje%2Flaebel/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrikje%2Flaebel/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrikje%2Flaebel/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/henrikje","download_url":"https://codeload.github.com/henrikje/laebel/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/henrikje%2Flaebel/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28417716,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T10:47:48.104Z","status":"ssl_error","status_checked_at":"2026-01-14T10:46:19.031Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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","documentation","readme","readme-generator"],"created_at":"2026-01-14T10:48:52.329Z","updated_at":"2026-01-14T10:48:54.611Z","avatar_url":"https://github.com/henrikje.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laebel\n\n_Automatic documentation site for your Docker Compose project._\n\nLaebel is a small server that runs in your Docker Compose project, serving a website that documents your project.\n\n\u003cfigure\u003e\n\u003ca href=\"./examples/react-express-mysql/README.md\"\u003e\u003cimg src=\"./examples/react-express-mysql/laebel-example-screenshot.png\" alt=\"Laebel output screenshot\"\u003e\u003c/a\u003e\n\u003cfigcaption\u003e\u003cem\u003eAn example of a documentation site generated by Laebel. \u003ca href=\"./examples/react-express-mysql/README.md\"\u003eView the full example\u003c/a\u003e.\u003c/em\u003e\u003c/figcaption\u003e\n\u003c/figure\u003e\n\u003cp\u003e\u003c/p\u003e\n\nLaebel uses the Docker API to get information about the services in your project,\nand then displays that information in an easy-to-read format.\nIt even includes a graph of how the services are connected.\nAdditional information about the services can be added using labels in the Docker Compose project.\n\nThe goal is to make it feel like someone wrote a nice README for your project, but without the manual work. 😀\n\n## Features\n\n- **Displays a service graph**: An easy-to-understand, visual representation of how the services in your project are connected. \n  It is based on [`depends_on`](https://docs.docker.com/reference/compose-file/services/#depends_on) relations in your Docker Compose project. \n  It also uses icons and color to visualize the status and health of the services.\n- **Live-updated status**: The status of the services is updated in real-time, so you can see when a service is starting, running, stopped, healthy, or unhealthy.\n- **Describes each service in your project**: Lists all services and the important information about them.\n  The information includes service name, image name, how many containers are running, and the status of the containers.\n- **Describes each volume and network**: Also displays information about each volume and network in your project.\n- **Additional user-configurable metadata**: Allows you to describe your services, volumes, and networks in more detail, \n  using [`labels`](https://docs.docker.com/reference/compose-file/services/#labels) in your Docker Compose project.\n  It allows you to specify title, description, group, external links, and more.\n  The metadata is based on the [OpenContainers Annotations Spec](https://specs.opencontainers.org/image-spec/annotations/) \n  but is extended through a set of Laebel-specific labels.\n- **Light and dark mode**: Supports both light and dark themes, and automatically switches based on the user's preference.\n\n## Usage\n\n### As a service in a Docker Compose project\n\nTo get started, add the following service to your Docker Compose project:\n\n```yaml\nlaebel:\n    image: ghcr.io/henrikje/laebel:latest\n    # Expose port 8000 to access the Laebel website\n    ports:\n    - \"8000:8000\"\n    # Mount the Docker socket in read-only mode\n    # This allows Laebel to detect the services in your project\n    volumes:\n    - \"/var/run/docker.sock:/var/run/docker.sock:ro\"\n```\n\nThen run `docker compose up` and open your browser at http://localhost:8000/ (or the host and port you use).\n\nFor a full example, see the [React-Express-MySQL example](./examples/react-express-mysql/README.md).\n\n### As a stand-alone container\n\nIf you do not want to add Laebel to your Compose Project, you can run Laebel as a stand-alone container.\nThen you need to tell Laebel which Compose Project to document using the environment variable `COMPOSE_PROJECT_NAME`.\n\n```bash\ndocker run \\\n  -e COMPOSE_PROJECT_NAME=\u003cyour-project\u003e \\\n  -v \"/var/run/docker.sock:/var/run/docker.sock:ro\" \\\n  -p 8000:8000 \\\n  ghcr.io/henrikje/laebel:latest\n```\n\nNote that in this case, you cannot put project metadata environment variables in the Compose Project.\nYou will have to manage those environment variables yourself.\n\n## Configuration\n\nLaebel will work out of the box and provide useful information about your project.\nHowever, it really shines when you add additional metadata about your Docker Compose project.\n\n### Documenting a project using labels\n\nLaebel reads metadata about each service, volume, and network from labels in the Docker Compose project.\nThis is used to describe the resources in more detail than what can be derived automatically from Docker.\n\nA short example of how to add documentation labels to a service:\n\n```yaml\nservices:\n  my-rest-api:\n    image: my-rest-api:latest\n    ports:\n      - 80:80\n    labels:\n      org.opencontainers.image.title: My REST API\n      org.opencontainers.image.description: My amazing REST API service that does cool things.\n      net.henko.laebel.group:  Public Services\n      net.henko.laebel.link.health.url: http://localhost/health\n      net.henko.laebel.link.health.title: Health Check\n      net.henko.laebel.port.80.description: The main HTTP port\n```\n\nThe most straight-forward way to add documentation is to add labels in your primary `compose.yaml` file.\nIf you want to keep the labels separate from the main configuration, you can use a `compose.override.yaml` file.\nDocker Compose will automatically [merge](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/) the two files\nwhen you run `docker compose`.\n\nAlternatively, you add labels to a service's `Dockerfile` so they will be built into the image:\n\n```Dockerfile\nLABEL org.opencontainers.image.title=\"My REST API\" \\\n      org.opencontainers.image.description=\"My amazing REST API service that does cool things.\" \\\n      net.henko.laebel.group=\"Public Services\" \\\n      net.henko.laebel.link.health.url=\"http://localhost/health\" \\\n      net.henko.laebel.link.health.title=\"Health Check\" \\\n      net.henko.laebel.port.80.description=\"The main HTTP port\"\n```\n\n### Available labels for services\n\nThe following [OpenContainers Annotations Spec](https://specs.opencontainers.org/image-spec/annotations/) labels are supported:\n\n- `org.opencontainers.image.title`: A human-readable title of the service.\n- `org.opencontainers.image.description`: A longer description of the service.\n- `org.opencontainers.image.url`: A URL to the service's homepage.\n- `org.opencontainers.image.documentation`: A URL to the documentation of the service.\n- `org.opencontainers.image.source`: A URL to the source code of the service.\n\nIn addition, Laebel supports the following custom labels:\n\n- `net.henko.laebel.group`: A group name to categorize services.\n  Services with the same group name will be displayed together, both in the service graph and in the list.\n- `net.henko.laebel.hidden`: If set to `true`, the service will not be displayed in the graph or the list.\n\nYou can also add any number of external links.\nThese are great for linking to documentation, administration interfaces, or other related services.\nEach link is specified with two labels, where `\u003ckey\u003e` can be any string:\n\n- `net.henko.laebel.link.\u003ckey\u003e.url`: The URL of the link.\n- `net.henko.laebel.link.\u003ckey\u003e.title`: The title of the link.\n- `net.henko.laebel.link.\u003ckey\u003e.description`: A description of the link.\n\nFinally, you can document the ports that are bound to the service.\nThis is especially helpful when it is not a well-known port.\n\n- `net.henko.laebel.port.\u003cport\u003e.description`: A description of the purpose of the port.\n  The `\u003cport\u003e` should be the port number that the container exposes (which may not be the same as the host port).\n\nSee the [full example](./examples/react-express-mysql/README.md) for examples on how to use these labels.\n\n### Available labels for volumes and networks\n\nLaebel also supports adding metadata to volumes and networks.\n\nThe following labels are supported:\n\n- `net.henko.laebel.title`: A human-readable title of the volume/network.\n- `net.henko.laebel.description`: A longer description of the volume/network.\n- `net.henko.laebel.hidden`: If set to `true`, the label/network will not be included in the generated documentation.\n\n### Project metadata through environment variables\n\nLaebel also supports setting metadata for the project as a whole.\nSince these values are not associated with any particular service, \nthey are specified by adding _environment variables_ to the `laebel` service in the Docker Compose project.\n\n- `LAEBEL_PROJECT_TITLE`: A human-readable title of the project.\n- `LAEBEL_PROJECT_DESCRIPTION`: A description of the project.\n- `LAEBEL_PROJECT_URL`: A URL to the project's homepage.\n- `LAEBEL_PROJECT_DOCUMENTATION`: A URL to the documentation of the project.\n- `LAEBEL_PROJECT_SOURCE`: A URL to the source code of the project.\n- `LAEBEL_PROJECT_LOGO`: A URL to an image file to use as the logo of the project.\n  Can be a `data:` URL to avoid external dependencies.\n\n## Feedback\n\nIf you have any thoughts or questions, please [reach out to me](https://henko.net/contact/).\n\n_Sidenote_: Why the name _Laebel_? \nIt is a reference to the idea that to label something is to explain what it is,\ncombined with the fact that Laebel relies on Docker _labels_ to get information about the project and its services.\nHowever, I also wanted to be a cool kid and use a [digraph](https://en.wikipedia.org/wiki/Digraph_(orthography)) like Traefik and Jaeger. 😉\n\n## License\n\nThis project is licensed under the terms of the [MIT license](LICENSE.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenrikje%2Flaebel","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhenrikje%2Flaebel","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhenrikje%2Flaebel/lists"}