{"id":13805727,"url":"https://github.com/tkrille/dropwizard-template-config","last_synced_at":"2026-01-11T07:54:37.238Z","repository":{"id":27007177,"uuid":"30471281","full_name":"tkrille/dropwizard-template-config","owner":"tkrille","description":"Dropwizard bundle that enables you to write your config.yaml as a Freemarker template.","archived":true,"fork":false,"pushed_at":"2023-12-16T07:13:38.000Z","size":102,"stargazers_count":50,"open_issues_count":0,"forks_count":16,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-08-04T01:05:21.835Z","etag":null,"topics":["configuration","dropwizard","dropwizard-bundle","microservices","template"],"latest_commit_sha":null,"homepage":"https://github.com/tkrille/dropwizard-template-config","language":"Groovy","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/tkrille.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}},"created_at":"2015-02-07T21:43:31.000Z","updated_at":"2024-08-02T21:56:53.000Z","dependencies_parsed_at":"2024-01-22T07:47:58.912Z","dependency_job_id":"5d6e2754-ee09-4deb-9bc0-36857b0f9e04","html_url":"https://github.com/tkrille/dropwizard-template-config","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkrille%2Fdropwizard-template-config","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkrille%2Fdropwizard-template-config/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkrille%2Fdropwizard-template-config/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tkrille%2Fdropwizard-template-config/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tkrille","download_url":"https://codeload.github.com/tkrille/dropwizard-template-config/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225254374,"owners_count":17445172,"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":["configuration","dropwizard","dropwizard-bundle","microservices","template"],"created_at":"2024-08-04T01:01:04.251Z","updated_at":"2026-01-11T07:54:37.189Z","avatar_url":"https://github.com/tkrille.png","language":"Groovy","funding_links":[],"categories":["Open Source"],"sub_categories":["Eclipse"],"readme":"# Dropwizard Template Config [![Circle CI](https://circleci.com/gh/tkrille/dropwizard-template-config/tree/master.svg?style=svg)](https://circleci.com/gh/tkrille/dropwizard-template-config/tree/master)\n\nA Dropwizard Bundle that allows you to write your `config.yaml` as a [Freemarker](http://freemarker.org) template.\nThis is especially useful when you need to access environment variables or system properties.\nIn fact, this project is the successor to the fabulous [dropwizard-environment-config](https://github.com/tkrille/dropwizard-environment-config) plugin.\n\n## Setup\n\nFirst add the dependency to your POM:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ede.thomaskrille\u003c/groupId\u003e\n    \u003cartifactId\u003edropwizard-template-config\u003c/artifactId\u003e\n    \u003cversion\u003e1.5.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nYour project is assumed to separately pull in `dropwizard-core` version 0.7.1 or newer.\nCompatibility has been tested through Dropwizard 1.0.0.\n\nTo enable, simply add the `TemplateConfigBundle` to the `Bootstrap` object in your `initialize` method:\n\n```java\n@Override\npublic void initialize(final Bootstrap\u003cConfiguration\u003e bootstrap) {\n    ...\n    bootstrap.addBundle(new TemplateConfigBundle());\n    ...\n}\n```\n\nYou can configure the bundle by passing an instance of `TemplateConfigBundleConfiguration` to the constructor:\n\n```java\n@Override\npublic void initialize(final Bootstrap\u003cConfiguration\u003e bootstrap) {\n    ...\n    bootstrap.addBundle(new TemplateConfigBundle(\n            new TemplateConfigBundleConfiguration().charset(Charsets.US_ASCII)\n    ));\n    ...\n}\n```\n\nYou can add your own variables to the template by adding your own implementations of the `TemplateConfigProvider`\nto the constructor:\n\n```java\n@Override\npublic void initialize(final Bootstrap\u003cConfiguration\u003e bootstrap) {\n    ...\n    bootstrap.addBundle(new TemplateConfigBundle(\n        new TemplateConfigBundleConfiguration()\n            .addCustomProvider(myCustomProvider1)\n            .addCustomProvider(myCustomProvider2)\n    ));\n    ...\n}\n```\n\nLook at `TemplateConfigBundleConfiguration`'s javadoc to see all available options.\n\n**Heads up:** The Bundle gets the content of the `config.yaml` by wrapping any previously defined\n`io.dropwizard.configuration.ConfigurationSourceProvider`.\nSo you must set any custom `ConfigurationSourceProvider` before adding this `Bundle` to the `Bootstrap`.\n\n## Quickstart\n\nEnvironment variables and system properties can be specified in `config.yaml` by using the following\nFreemarker magic:\n\n```yaml\nserver:\n  type: simple\n  connector:\n    type: http\n    # replacing environment variables\n    port: ${PORT}\nlogging:\n  # with default values too\n  level: ${LOG_LEVEL!'WARN'}\n  appenders:\n    # system properties also work\n    - type: ${log_appender!'console'}\n```\n\nSee [Freemarker's Template Author's Guide](http://freemarker.org/docs/dgui.html) for more information\non how to write templates.\n\n## Tutorial\n\nUsing this bundle you can write your `config.yaml` as [Freemarker](http://freemarker.org) template.\nLet's start with a simple example: replacing environment variables.\nFor all the Heroku users out there, we will try to use Heroku's environment variables for the examples.\nLet's focus on a single piece of the configuration shown in the [Quickstart](#quickstart):\n\n```yaml\nserver:\n  type: simple\n  connector:\n    type: http\n    port: ${PORT}\n```\n\nYou can specify a default value in case the environment variable is missing.\nThis is useful for local tests on your development machine:\n\n```yaml\nserver:\n  type: simple\n  connector:\n    type: http\n    port: ${PORT!8080}\n```\n\nDefault values are separated from the variable name by a `!` and follow more or less the well-known\nJava syntax for scalars.\nIf there is no default value for a missing variable an exception will be thrown by Freemarker and wrapped\nin a `RuntimeException`.\nJava system properties (the contents of `System.getProperties()`) are available, too:\n\n```yaml\nserver:\n  type: simple\n  connector:\n    type: http\n    port: ${http_port}\n```\n\nThere are some limitations to the variables and properties you can access through these top-level variables.\nFor one, environment variables and system properties with the same name will collide (environment variables\nwill mask system properties in this case).\nFor another, names containing [characters such as `.` and `-` that have special meaning to Freemarker]\n(http://freemarker.org/docs/dgui_template_exp.html#dgui_template_exp_var_toplevel) won't be available.\nTo alleviate these problems, this bundle also provides `Map`s for the environment (`env`) and system\nproperties (`sys`) at the top level:\n\n```yaml\n# Use `sys` to access a system property masked by an environment variable\nport: ${sys.http_port}\n\n# Use bracket notation to access a system property with a `.` in its name\nport: ${sys['my_app.http.port']}\n\n# Names with a dash (`-`) can be accessed via brackets or backslash\nport: ${sys['http-port']}\nport: ${http\\-port}\n```\n\nYou can output variables inline in values.\nThis is helpful to specify the database connection:\n\n```yaml\ndatabase:\n  driverClass: org.postgresql.Driver\n  user: ${DB_USER}\n  password: ${DB_PASSWORD}\n  url: jdbc:postgresql://${DB_HOST!'localhost'}:${DB_PORT}/my-app-db\n```\n\nIn fact, you can output anything anywhere, because Freemarker doesn't know anything about YAML:\n\n```yaml\n#\n# Given the following environment:\n#\n# SERVER_TYPE_LINE='type: simple'\n# SERVER_CONNECTOR_TYPE_LINE='type: http'\n#\nserver:\n  ${SERVER_TYPE_LINE}\n  connector:\n    ${SERVER_CONNECTOR_TYPE_LINE}\n    port: 8080\n```\n\nBe careful though, not to mess up YAML's data structure.\nOf course, you can use any other Freemarker features beyond simple variable interpolation:\n\n```yaml\n# Use with:\n#\n# ENABLE_SSL=true\n# SSL_PORT=8443 (optional)\n# SSL_KEYSTORE_PATH=/etc/my-app/keystore\n# SSL_KEYSTORE_PASS=secret\n#\n# or\n#\n# ENABLE_SSL=false\n#\nserver:\n  applicationConnectors:\n    - type: http\n      port: ${PORT!8080}\n\u003c#if ENABLE_SSL == 'true'\u003e\n    - type: https\n      port: ${SSL_PORT!8443}\n      keyStorePath: ${SSL_KEYSTORE_PATH}\n      keyStorePassword: ${SSL_KEYSTORE_PASS}\n\u003c/#if\u003e\n```\n\nThe previous example conditionally enables HTTPS if the environment variable `ENABLE_SSL` is `true`.\nComments are available too:\n\n```yaml\nserver:\n  applicationConnectors:\n    - type: http\n      port: ${PORT!8080}\n\u003c#-- Un-comment to enable HTTPS\n    - type: https\n      port: ${SSL_PORT!8443}\n      keyStorePath: ${SSL_KEYSTORE_PATH}\n      keyStorePassword: ${SSL_KEYSTORE_PASS}\n--\u003e\n```\n\nComments are writen between the `\u003c#-- --\u003e` Freemarker tags.\nThey can span multiple lines.\nAnother advanced use case might be introducing configuration profiles that can be switched by using\nan environment variable like this:\n\n```yaml\nlogging:\n\u003c#if PROFILE == 'production'\u003e\n  level: WARN\n  loggers:\n    com.example.my_app: INFO\n    org.hibernate.SQL: OFF\n  appenders:\n    - type: syslog\n      host: localhost\n      facility: local0\n\u003c#elseif PROFILE == 'development'\u003e\n  level: INFO\n  loggers:\n    com.example.my_app: DEBUG\n    org.hibernate.SQL: DEBUG\n  appenders:\n    - type: console\n\u003c/#if\u003e\n```\n\n\nYou can include snippets from external config files via the `\u003c#include\u003e` tag.\nFor this to work, you have to set an include directory\nbased either on a resource in the classpath:\n\n```java\n@Override\npublic void initialize(final Bootstrap\u003cConfiguration\u003e bootstrap) {\n    ...\n    bootstrap.addBundle(new TemplateConfigBundle(\n            new TemplateConfigBundleConfiguration().resourceIncludePath(\"/config\")\n    ));\n    ...\n}\n```\n\nor on the local filesystem:\n\n```java\n@Override\npublic void initialize(final Bootstrap\u003cConfiguration\u003e bootstrap) {\n    ...\n    bootstrap.addBundle(new TemplateConfigBundle(\n            new TemplateConfigBundleConfiguration().fileIncludePath(\"./config\")\n    ));\n    ...\n}\n```\n\nFeel free to use sub-folders to organize your configurations.\nWhile the argument to `fileIncludePath` may be relative to the current working\ndirectory or absolute, the argument to `resourceIncludePath` will always\nbe made absolute by prepending a slash (`/`) if not present.\nYou can then include configuration templates from other files.\nTo extract the database config, for example, create a config like this:\n\n```yaml\nserver:\n  type: simple\n  connector:\n    type: http\n    port: 8080\n\n\u003c#include \"database.yaml\"\u003e\n\nlogging:\n  level: WARN\n```\n\nThe `database.yaml` looks like this:\n\n```yaml\ndatabase:\n  driverClass: org.postgresql.Driver\n  user: my-app\n  password: secret\n  url: jdbc:postgresql://localhost:5432/my-app-db\n```\n\nThe result will look like this:\n\n```yaml\nserver:\n  type: simple\n  connector:\n    type: http\n    port: 8080\n\ndatabase:\n  driverClass: org.postgresql.Driver\n  user: my-app\n  password: secret\n  url: jdbc:postgresql://localhost:5432/my-app-db\n\nlogging:\n  level: WARN\n```\n\nOf course, you can also use any templating feature in the included file, like:\n\n- accessing environment variables\n- using conditionals\n- including additional files\n\nIf you're not seeing the behavior you expect, it can be useful to inspect the rendered text of your template.\nSince 1.3.0, you can provide an `outputPath` to which the bundle will write the filled-out text of the\nconfig before passing it on to Dropwizard:\n\n```java\n@Override\npublic void initialize(final Bootstrap\u003cConfiguration\u003e bootstrap) {\n    ...\n    bootstrap.addBundle(new TemplateConfigBundle(\n            new TemplateConfigBundleConfiguration().outputPath(\"/tmp/config.yml\")\n    ));\n    ...\n}\n```\n\nBe careful to not overuse all this stuff.\nIn the end, a configuration file should stay as simple as possible and be easily readable.\nExtensively using advanced Freemarker features might get in the way of this principle.\n\nSee [Freemarker's Template Author's Guide](http://freemarker.org/docs/dgui.html) for more information\non how to write templates.\n\n## Migration from Dropwizard Environment Config\n\nTODO: write me!\n\n## Copyright Notice\n\nThis project is licensed under the Apache License, Version 2.0, January 2004, and uses the following\n3rd party software:\n\n- Dropwizard\n\n    Copyright 2010-2015, Coda Hale, Yammer Inc.\n\n- Freemarker\n\n    Copyright 2002-2015, The FreeMarker Project, Attila Szegedi, Daniel Dekany,\n    Jonathan Revusky\n\nSee LICENSE-3RD-PARTY and NOTICE-3RD-PARTY for the individual 3rd parties.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkrille%2Fdropwizard-template-config","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftkrille%2Fdropwizard-template-config","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftkrille%2Fdropwizard-template-config/lists"}