{"id":17809292,"url":"https://github.com/codfish/json-server-docker","last_synced_at":"2025-03-17T16:30:45.557Z","repository":{"id":52646248,"uuid":"177173473","full_name":"codfish/json-server-docker","owner":"codfish","description":"Docker image to easily integrate json-server mock api's into your app.","archived":false,"fork":false,"pushed_at":"2023-10-29T00:10:46.000Z","size":877,"stargazers_count":18,"open_issues_count":1,"forks_count":5,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-28T01:38:06.458Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/codfish/json-server","language":"JavaScript","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/codfish.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":"2019-03-22T16:20:34.000Z","updated_at":"2024-12-10T03:18:34.000Z","dependencies_parsed_at":"2023-10-29T00:30:17.396Z","dependency_job_id":null,"html_url":"https://github.com/codfish/json-server-docker","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codfish%2Fjson-server-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codfish%2Fjson-server-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codfish%2Fjson-server-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codfish%2Fjson-server-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codfish","download_url":"https://codeload.github.com/codfish/json-server-docker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243871361,"owners_count":20361338,"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":[],"created_at":"2024-10-27T15:16:20.640Z","updated_at":"2025-03-17T16:30:45.060Z","avatar_url":"https://github.com/codfish.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# json-server-docker\n\nDockerized [json-server](https://github.com/typicode/json-server) for building a full fake RESTful\nAPI.\n\n[![version](https://img.shields.io/docker/v/codfish/json-server/0.17.3)](https://hub.docker.com/r/codfish/json-server)\n[![pulls](https://img.shields.io/docker/pulls/codfish/json-server.svg)](https://hub.docker.com/r/codfish/json-server)\n[![MIT License](https://img.shields.io/github/license/codfish/json-server-docker)](http://opensource.org/licenses/MIT)\n\n\u003e Created with \u003c3 for front-end developers who need a quick back-end for prototyping and mocking.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Features](#features)\n- [Getting Started](#getting-started)\n- [Usage](#usage)\n  - [Docker Compose (Recommended)](#docker-compose-recommended)\n  - [Docker cli](#docker-cli)\n  - [Advanced](#advanced)\n  - [Important Usage Notes](#important-usage-notes)\n- [Database File](#database-file)\n- [Middleware](#middleware)\n  - [Using Multiple Middleware files](#using-multiple-middleware-files)\n- [Typescript Support](#typescript-support)\n- [Options](#options)\n- [Maintaining/Contributing](#maintainingcontributing)\n  - [Releasing](#releasing)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Features\n\n- 💨 **Up and running quickly** - Spin up a RESTful mock API in seconds.\n- ⚙️ **Configurable** - Supports every `json-server` configuration option, with some purposeful\n  exceptions.\n- \u003cimg src=\"ts.png\" width=\"16\" height=\"16\"\u003e **Typescript support** - Use TS for your db, middleware,\n  or any file you mount into the container.\n- 💻 **Mount in any supporting files you'd like!** - For instance, want to use your custom data\n  fixtures, utils, etc. in your db/middleware? Mount them in, import \u0026 prosper.\n- 📦 **Useful dependencies are pre-installed** in the image for your convenience. Use\n  [`lodash`](https://lodash.com/), [`@faker-js/faker`](https://github.com/faker-js/faker) \u0026\n  [`jwt-decode`](https://github.com/auth0/jwt-decode) in any of the files powering your mock api.\n- 🧳 **Install your own dependencies** - Use the `DEPENDENCIES` envvar to pass a list of additional\n  npm dependencies to use in your server files.\n- 🔂 **Hot reloading** the server on any changes.\n\n## Getting Started\n\n**Latest Version**: `codfish/json-server:0.17.3`\n\n\u003e **Note**: It's recommended to specify the tag of the image you want rather than using the latest\n\u003e image, which might break. Image tags are based off of the\n\u003e [release versions for json-server](https://github.com/typicode/json-server/releases). However\n\u003e there is not an image for every version. See the available versions\n\u003e [here](https://hub.docker.com/r/codfish/json-server/tags).\n\nBy default, the image runs an instance of `json-server` with some dummy data for show. Spin up the\nexample mock api in seconds.\n\n```sh\ndocker run -p 9999:80 codfish/json-server:0.17.3\n```\n\nVisit \u003chttp://localhost:9999\u003e to see it in action.\n\nThat's all good, but not very useful to you. You're meant to mount in your own db file(s) into the\ncontainer. Read on for usage...\n\n## Usage\n\nThis project actually dogfoods itself. View the [docker-compose.yml](./docker-compose.yml) \u0026 the\n[examples/](./examples/) directory to see various usage examples. Also visit the\n[`json-server` docs](https://github.com/typicode/json-server) for more detailed examples on how to\nuse the tool.\n\n**Examples**\n\n- [Simple json file](./examples/json/)\n- [Multiple middlewares](./examples/middlewares/)\n- [Installing extra dependencies](./examples/deps/)\n- [Typescript](./examples/typescript/)\n- [Mount in additional files](./examples/support-files/)\n\n### Docker Compose (Recommended)\n\n```yml\nversion: '3'\n\nservices:\n  api:\n    image: codfish/json-server:0.17.3\n    ports:\n      - 9999:80\n    volumes:\n      - ./my-db.js:/app/db.js:delegated\n      - ./my-middleware.js:/app/middleware.json:delegated\n      - ./my-routes.json:/app/routes.json:delegated\n```\n\nRun `docker-compose up api`. Visit \u003chttp://localhost:9999/\u003e to see your API.\n\n### Docker cli\n\n```sh\ndocker run -d -p 9999:80 \\\n  -v ./my-db.js:/app/db.js \\\n  -v ./my-middleware.js:/app/middleware.json \\\n  -v ./my-routes.json:/app/routes.json \\\n  codfish/json-server:0.17.3\n```\n\n### Advanced\n\nSet configuration via environment variables.\n\n```yaml\nservices:\n  json-server:\n    image: codfish/json-server:0.17.3\n    volumes:\n      - ./db.ts:/app/db.ts:delegated\n      - ./middleware.ts:/app/middleware.ts:delegated\n      - ./routes.json:/app/routes.json:delegated\n    environment:\n      FKS: Address\n      ID: address\n      NO_CORS: true\n      NO_GZIP: true\n```\n\nSee all the [available options below](#options).\n\n### Important Usage Notes\n\n\u003e - **LIMITATION**: `json-server` ONLY supports `commonjs`! If you try to use any ESM dependency in\n\u003e   your db files, it will fail. For our Typescript support, while ESM is supported in your db\n\u003e   files, we're [compiling](./tsconfig.json) to target es5 \u0026 commonjs and dependencies are not\n\u003e   compiled, so when using 3rd party deps, use versions that export commonjs modules.\n\n- Your `db.{js,ts}` \u0026 any middleware files need to return a function as their **default** export.\n- When mounting `*.js` files, make sure they are using commonjs (`modules.exports = ...`). That's\n  what `json-server` is expecting.\n- When mounting `*.ts` files, use ESModules, but instead of using `export default ...`, use\n  `export = ...`.\n- All files should be mounted into the `/app` directory in the container.\n- The following files are special and will \"just work\" when **mounted over**.\n  - `/app/db.{ts,js,json}` - The database file.\n  - `/app/middleware.{ts,js}` - Custom\n    [middleware file](https://github.com/typicode/json-server#add-middlewares).\n  - `/app/routes.json` - Custom\n    [routes file](https://github.com/typicode/json-server#add-custom-routes).\n  - `/public` - Static files directory.\n\n## Database File\n\nWhen building your mock api's you'll most like want to generate some fake data and return a number\nof items for a specific collection. [Faker](https://github.com/faker-js/faker) is included in the\nimage to help facilitate doing these sorts of things inside your db or middleware files. For\nexample:\n\n```js\n// db.js\nconst times = require('lodash/times');\nconst faker = require('@faker-js/faker');\n\nmodule.exports = (req, res) =\u003e {\n  return {\n    posts: times(100, () =\u003e ({\n      id: faker.datatype.uuid(),\n      title: faker.lorem.words(3),\n      body: faker.lorem.paragraphs(3),\n    })),\n  };\n};\n```\n\n## Middleware\n\nExample middleware.\n\n```ts\n// middleware.ts\nimport { faker } from '@faker-js/faker';\n\nexport = (req, res, next) =\u003e {\n  // If you're making an ajax request and not viewing in the browser, require an Authorization header.\n  if (!req.accepts('html') \u0026\u0026 !req.header('Authorization')) {\n    res.status(401).send();\n  }\n\n  // Force uuid's for id's for primary keys instead of integers.\n  if (req.method === 'POST') {\n    req.body.id = faker.string.uuid();\n  }\n\n  next();\n};\n```\n\n### Using Multiple Middleware files\n\nUse the `MIDDLEWARES` to pass the\n[`--middlewares`](https://github.com/typicode/json-server#add-middlewares) option to `json-server`.\n\n**Important**: Notice here the files you're mounting in are using \\*.ts extentions, but the\n`MIDDLEWARES` env var uses `js` extensions. TS compiling happens _before_ `json-server` loads the\nfiles.\n\n```yml\nservices:\n  middlewares:\n    image: .\n    volumes:\n      - ./db.json:/app/db.json\n      - ./middleware_a.ts:/app/middleware_a.ts:delegated\n      - ./middleware_b.ts:/app/middleware_b.ts:delegated\n    ports:\n      - 9996:80\n    environment:\n      VIRTUAL_HOST: middlewares.json-server.docker\n      MIDDLEWARES: 'middleware_a.js middleware_b.js'\n```\n\n## Typescript Support\n\n**Important**\n\n- Instead of using `export default ...`, use `export = ...` for any default exports from your ts\n  files.\n- TS is [configured](./tsconfig.json) to target commonjs es5 modules to work well with\n  `json-server`.\n- A [path alias](https://www.typescriptlang.org/tsconfig#paths) is configured for your convenience\n  to map to the `/app` directory where all server files should be mounted.\n- You can technically mount in your tsconfig file (`-v ./tsconfig.json:/app/tsconfig.json`) with\n  your own configuration file, but beware, `json-server` needs the resulting compiled files to be\n  commonjs modules.\n\n```ts\n// db.ts\nimport { faker } from '@faker-js/faker';\n\ninterface Database {\n  posts: Array\u003c{\n    id: string;\n    title: string;\n    body: string;\n  }\u003e;\n}\n\nexport = (): Database =\u003e ({\n  posts: faker.helpers.multiple(\n    () =\u003e ({\n      id: faker.string.uuid(),\n      title: faker.lorem.words(3),\n      body: faker.lorem.paragraphs(3),\n    }),\n    { count: 10 },\n  ),\n});\n```\n\n```sh\ndocker run -d -p 9999:80 -v ./db.ts:/app/db.ts codfish/json-server\n```\n\n## Options\n\n`json-server` cli options: \u003chttps://github.com/typicode/json-server#cli-usage\u003e\n\nWe will use the default options that `json-server` has set unless an override is provided. For\ncertain options like `--port` and `--host` we will explicitly set them to work well within a\ncontainer.\n\nHere's the list of `json-server` options that are **NOT** configurable:\n\n- `--host` - Always set to `0.0.0.0` within the container.\n- `--port` - Always set to `80` within the container but you're still in full control of what port\n  you want the api to run on on your machine by mapping any port to port `80` on the container (i.e.\n  `docker run -p 9999:80 ...`).\n- `--routes` - The `/app/routes.json` will always be the path to the\n  [routes file](https://github.com/typicode/json-server#add-custom-routes) used in the container,\n  but you're free to mount any json file from your machine over it.\n\nHowever you still have the ability to override _almost_ every option yourself as well. All options\nshould be **passed in as environment variables**. They are named exactly like `json-server`'s but\nupper snake-case (i.e. `--no-cors` -\u003e `NO_CORS`).\n\n`⋆` = Custom option. Not an official `json-server` option.\n\n| Option           | Description                                                                          | Default                                                                         |\n| ---------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |\n| `MIDDLEWARES`    | Path to middleware file                                                              | `middleware.js` (Stored in image, optionally mount over it or provide your own) |\n| `CONFIG`         | Path to config file                                                                  | Defers to `json-server` default                                                 |\n| `SNAPSHOTS`      | Set snapshots directory                                                              | Defers to `json-server` default                                                 |\n| `ID`             | Set database id property (e.g. `address`)                                            | Defers to `json-server` default                                                 |\n| `FKS`            | Set foreign key suffix, (e.g. `_id` as in `user_id`)                                 | Defers to `json-server` default                                                 |\n| `DELAY`          | Add delay to responses (ms)                                                          | —                                                                               |\n| `STATIC`         | Set static files directory                                                           | Defers to `json-server` default                                                 |\n| `QUIET`          | Suppress log messages from output                                                    | Boolean flag only true if set to \"true\"                                         |\n| `NO_GZIP`        | Disable GZIP Content-Encoding                                                        | Boolean flag only true if set to \"true\"                                         |\n| `NO_CORS`        | Disable Cross-Origin Resource Sharing                                                | Boolean flag only true if set to \"true\"                                         |\n| `READ_ONLY`      | Allow only GET requests                                                              | Boolean flag only true if set to \"true\"                                         |\n| ⋆ `DEPENDENCIES` | Install extra npm dependencies in the container for you to use in your server files. | —                                                                               |\n\nFor details on the options\n[view `json-server`'s documentation](https://github.com/typicode/json-server#cli-usage).\n\n## Maintaining/Contributing\n\nThis project actually dogfoods itself. To test it directly you can run:\n\n```sh\ngit clone git@github.com:codfish/json-server-docker.git\ncd json-server-docker\ndocker-compose up -d\n```\n\n**To update:**\n\n- Bump version of `json-server` in [`Dockerfile`](./Dockerfile)\n- Bump node dependencies\n- Test it out\n\n```sh\ndocker-compose up -d --build\n```\n\nVisit \u003chttp://localhost:9999\u003e. Update [`db.js`](./db.ts), [`routes.json`](./routes.json), or\n[`middleware.ts`](./middleware.ts) to test out functionality. Changes should propagate\nautomatically, just refresh the page.\n\n### Releasing\n\n**New version**:\n\n```sh\ngit tag -f -m '0.17.3' 0.17.3\ngit push origin 0.17.3\n```\n\n**Updating old version**\n\nWe keep our versions in sync with `json-server`. This scenario would happen if there's a bug fix or\nfeature change with our implementation but the `json-server` version doesn't change.\n\n```sh\ngit tag -fa 0.16.1 -m \"Update 0.16.1 tag\" \u0026\u0026 git push origin 0.16.1 --force\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodfish%2Fjson-server-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodfish%2Fjson-server-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodfish%2Fjson-server-docker/lists"}