{"id":16517589,"url":"https://github.com/thiamsantos/shipator","last_synced_at":"2025-10-28T06:32:06.146Z","repository":{"id":45503579,"uuid":"346715632","full_name":"thiamsantos/shipator","owner":"thiamsantos","description":"Inject environment variables into static files at runtime","archived":false,"fork":false,"pushed_at":"2022-01-05T12:55:39.000Z","size":63,"stargazers_count":8,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-01T12:11:16.506Z","etag":null,"topics":["docker","react"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/finbits/shipator","language":"Go","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/thiamsantos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-03-11T13:43:38.000Z","updated_at":"2023-04-27T07:18:58.000Z","dependencies_parsed_at":"2022-07-15T09:17:08.365Z","dependency_job_id":null,"html_url":"https://github.com/thiamsantos/shipator","commit_stats":null,"previous_names":["finbits/shipator"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiamsantos%2Fshipator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiamsantos%2Fshipator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiamsantos%2Fshipator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thiamsantos%2Fshipator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thiamsantos","download_url":"https://codeload.github.com/thiamsantos/shipator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":238607632,"owners_count":19500222,"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","react"],"created_at":"2024-10-11T16:32:40.511Z","updated_at":"2025-10-28T06:32:00.872Z","avatar_url":"https://github.com/thiamsantos.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/Finbits/shipator/main/logo.svg\" height=\"120\" alt=\"Shipator\" /\u003e\n\n[![CI](https://github.com/Finbits/shipator/workflows/CI/badge.svg?branch=main)](https://github.com/Finbits/shipator/actions/workflows/CI.yml?query=branch%3Amain)\n[![GitHub release](https://img.shields.io/github/v/release/Finbits/shipator)](https://github.com/Finbits/shipator/releases/latest)\n[![Go Report Card](https://goreportcard.com/badge/github.com/Finbits/shipator)](https://goreportcard.com/report/github.com/Finbits/shipator)\n[![License](https://img.shields.io/github/license/Finbits/shipator)](https://github.com/Finbits/shipator/blob/main/LICENSE)\n\nInject environment variables into static files at runtime.\n\n## Background\n\nThe common front-end build tools (like [CRA][CRA]) inject the env vars at build time.\nThis means if we want to deploy the static files in a docker environment,\nwe need to build a different docker image for each environment, as the URL for\nthe server and other values that usually come from an env var will be inlined in the final bundle.\nThis behaviour prevents the docker image to be built once and run anywhere - on any\nenvironment (dev, test, staging, prod) - just requiring us to provide the different configuration of each environment.\n\nThis project aims to feel this gap by allowing to inject environment variables into\nstatic files at runtime using the [approach mentioned at the `CRA` documentation](https://create-react-app.dev/docs/title-and-meta-tags#injecting-data-from-the-server-into-the-page).\n\nAnother option would be to serve the application using a [Node.js][Node.js] webserver to inject the\nenv vars in each request. Shipator takes a different approach by trying to keep working\nexclusively with static files in order to leverage high-performance webservers like\n[ngnix](https://www.nginx.com/) to serve the files while enabling us to inject env vars at runtime.\n\n## How it works\n\nShipator will replace a placeholder (like `__ENV__`) of a targeted static file with the allowed env vars.\n\nIt ships with an official docker image that uses [OpenResty](OpenResty)\n(a [ngnix](https://www.nginx.com/) distribution) to serve the files. Whenever the container starts,\nit will read all the env vars starting with the prefix defined at `SHIPATOR_PREFIX` (default `REACT_APP`),\nand inject the env vars in the place of the placeholder defined at `SHIPATOR_PLACEHOLDER` (default `__ENV__`)\nof the target file defined at `SHIPATOR_TARGET` (default `/app/shipator/html/index.html`).\nAfter the replace the ngnix server will be started to serve the static files.\n\n## Docker Usage\n\nNote: The following example assumes that your project was generated by [CRA][CRA]\nhowever, all the steps can be applied to different setups given a few minor modifications.\n\n1. Update the `public/index.html` of your project, inserting the `__ENV__` to be\ninjected at runtime, but fallbacking to the build time env vars that [CRA][CRA]\nprovides, so it works locally normally.\n\nInsert the following snippet right before the `\u003c/head\u003e` closing tag.\n\n```html\n\u003cscript\u003e\n  window.ENV = (function() {\n    try {\n      return __ENV__;\n    } catch (e) {\n      return {};\n    }\n  })();\n  window.ENV.REACT_APP_SERVER_URL =\n    window.ENV.REACT_APP_SERVER_URL || '%REACT_APP_SERVER_URL%';\n\u003c/script\u003e\n```\n\n2. Update the rest of the project to get the values from this global variable:\n\n```ts\nconst baseUrl = window.ENV.REACT_APP_SERVER_URL;\n```\n\n3. Create a Dockerfile using shipator\n\n```docker\nFROM node:12.16.1-alpine as builder\nWORKDIR /app\nCOPY yarn.lock /app/yarn.lock\nCOPY package.json /app/package.json\nRUN yarn install --frozen-lockfile\nCOPY . /app\nRUN yarn build\n\nFROM Finbits/shipator:1.0.2\nCOPY --from=builder /app/build /app/shipator/html\n```\n\n4. Build the docker image.\n\n```sh\n$ docker build --rm -t my-webapp:latest .\n```\n\n5. Start the webserver\n\n```\n$ docker run --rm -p 3000:80 -e REACT_APP_SERVER_URL=http://my-api.com my-webapp:latest\n```\n\n6. Now open your browser at http://localhost:3000.\n\nIf you open your dev tools console, and write `window.ENV.REACT_APP_SERVER_URL`,\nit will return `http://my-api.com`.\n\nNote: If you use [kubernetes](https://kubernetes.io/) in production the env vars\ncould be placed in a configmap, with different values for each deployment environment.\n\n## CLI Usage\n\nYou can also use the shipator CLI directly. You can download it on the [releases page](https://github.com/Finbits/shipator/releases).\n\n```\nUsage\n  $ shipator [options] target\n\nOptions\n  -placeholder string\n        Placeholder in the target (default \"__ENV__\")\n  -prefix string\n        Prefix of the env vars to inject (default \"REACT_APP\")\n  -version\n        Prints current version\n\nExamples\n  $ shipator build/index.html\n  $ shipator -prefix REACT_APP -placeholder __ENV__ build/index.html\n  $ shipator -placeholder __VARS__ build/index.html\n  $ shipator -prefix VUE_APP build/index.html\n```\n\n## Changelog\n\nSee the [changelog](https://github.com/Finbits/shipator/blob/main/CHANGELOG.md).\n\n## Contributing\n\nSee the [contributing file](https://github.com/Finbits/shipator/blob/main/CONTRIBUTING.md).\n\n## License\n\nCopyright 2021 © Finbits.\n\nShipator source code is released under Apache 2 License.\n\nCheck [LICENSE](https://github.com/Finbits/shipator/blob/main/LICENSE) file for more information.\n\n[CRA]: https://create-react-app.dev\n[Node.js]: https://nodejs.org\n[nginx]: https://www.nginx.com\n[OpenResty]: https://openresty.org\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiamsantos%2Fshipator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthiamsantos%2Fshipator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthiamsantos%2Fshipator/lists"}