{"id":28523459,"url":"https://github.com/keystonejs/keystone-6-heroku-example","last_synced_at":"2025-07-06T05:31:35.794Z","repository":{"id":46057224,"uuid":"399658514","full_name":"keystonejs/keystone-6-heroku-example","owner":"keystonejs","description":"A simple example project of showing how you might deploy Keystone 6 to Heroku","archived":false,"fork":false,"pushed_at":"2021-12-01T03:52:11.000Z","size":293,"stargazers_count":15,"open_issues_count":3,"forks_count":15,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-06-09T10:08:59.404Z","etag":null,"topics":["heroku","keystonejs"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/keystonejs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-08-25T01:57:02.000Z","updated_at":"2024-02-26T13:44:53.000Z","dependencies_parsed_at":"2022-08-26T04:30:38.761Z","dependency_job_id":null,"html_url":"https://github.com/keystonejs/keystone-6-heroku-example","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/keystonejs/keystone-6-heroku-example","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystonejs%2Fkeystone-6-heroku-example","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystonejs%2Fkeystone-6-heroku-example/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystonejs%2Fkeystone-6-heroku-example/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystonejs%2Fkeystone-6-heroku-example/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/keystonejs","download_url":"https://codeload.github.com/keystonejs/keystone-6-heroku-example/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/keystonejs%2Fkeystone-6-heroku-example/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263853279,"owners_count":23520117,"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":["heroku","keystonejs"],"created_at":"2025-06-09T10:08:36.027Z","updated_at":"2025-07-06T05:31:35.787Z","avatar_url":"https://github.com/keystonejs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keystone 6 on Heroku\n\nA simple example project showing how one might develop and deploy a [KeystoneJS 6](https://keystonejs.com)\nbackend to [Heroku](https://www.heroku.com/).\n\n![keystone-heroku-2](https://user-images.githubusercontent.com/6447754/133170735-d7887eba-cda5-41a2-9780-d6f287d01956.png)\n\nThe app code in this project is based heavily on the\n[`with-auth` example project](https://github.com/keystonejs/keystone/tree/master/examples/with-auth) from the main\n[Keystone repo](https://github.com/keystonejs/keystone).\nIt demonstrates some of the powerful APIs and tools Keystone provides and the gratifying developer experience it enables.\n\nIf you haven't heard about [Keystone](https://keystonejs.com), it's a powerful GraphQL-based headless CMS, written in TypeScript\nIt has some terrific features out of the box, is easy to extend, and a joy to use.\nThere's [documentation](https://keystonejs.com/docs) covering all the\n[APIs](https://keystonejs.com/docs/apis) and\n[field types](https://keystonejs.com/docs/apis/fields) used in this project, as well as\n[guides](https://keystonejs.com/docs/guides) to take you further.\n\nIf you get stuck, hit us up on the [KeystoneJS Slack](https://community.keystonejs.com) and search (or post) under the\n[`[keystonejs]` tag](https://stackoverflow.com/questions/tagged/keystonejs) on Stack Overflow.\n\n## How to Use This Repo\n\nThere are different ways to approach this repo depending on what you're trying to achieve:\n\n* **[Deploy directly to Heroku](#deploy-directly-to-heroku) (for free!)** –\nClick the \"Deploy\" button below to build and run a live copy of this app on your own Heroku account.\nThis is a good way to play around with the Keystone Admin UI without setting up a local dev environment.\n* **[Download the code to experiment locally](#develop-locally)** –\nGit clone or download the source code to experiment with Keystone 6 on your own machine.\nCustomise the lists and Admin UI, play with the GraphQL endpoint, setup access control and more.\n* **[Start a new project](#start-a-new-project)** –\nWant to use this repo as a template for your own project?\nFork it to your GitHub account and start hacking.\nThe instructions below guide you through creating a Heroku app using the \"push to deploy\" workflow.\nYou'll have a powerful and immensely flexible GraphQL backend, live on the Internet, in no time\n* **Just look around** –\nDon't need to run the app?\nBrowse the source code here on GitHub as a reference implementation.\nWe've tried to include helpful comments inline and the `with-auth` example project (on which this app is based) has further\n[documentation](https://github.com/keystonejs/keystone/tree/master/examples/with-auth).\n\n## Deploy Directly to Heroku\n\n[![Deploy Directly to Heroku](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/keystonejs/keystone-6-heroku-example)\n\nThis magical button 👆 takes a copy of this repo, builds it into an image and runs it on a Heroku dyno with the Postgres addon.\nAll you need to get started is a [Heroku account](https://signup.heroku.com).\n\nThese resources are created on the [free tier](https://www.heroku.com/pricing) so, naturally,\nhave some performance limitations and will \"sleep\" if no request are made for a few minutes.\nWith this option you also won't be able to modify the source code or data schema (for that, you'll need to setup a local dev environment, see below).\nRegardless this is a great, low investment way to play with the Keystone Admin UI from a user perspective.\n\n## Develop Locally\n\nThis codebase can be run and developed on your local machine by setting up a simple development environment.\n\nFirst, ensure you have the following tools installed:\n\n* [git](https://git-scm.com/downloads)\n* [NodeJS](https://nodejs.org/en/download) (v14.13 or higher)\n* [Yarn](https://classic.yarnpkg.com/en/docs/install) (or `npm` will also work)\n* [PostgreSQL](https://www.postgresql.org/download)\n\nIf you're on MacOS and use [Homebrew](https://brew.sh), you can install all these at once:\n\n```sh\nbrew install git node yarn postgresql\n```\n\nIf you're on a different platform, click though the links above and follow the relevant instructions.\n\nOnce the prerequisites are installed we can download the app code:\n\n```sh\n# Download the repo\ngit clone https://github.com/keystonejs/keystone-6-heroku-example\ncd keystone-6-heroku-example\n\n# Install the node packages\nyarn\n\n# Start the app\nyarn dev\n```\n\nThen, point your browser to [localhost:3000](http://localhost:3000).\nYou'll be prompted to set an email address and password before being taken to the Keystone Admin UI.\n\n### Modifying the App\n\nThis app is extremely simple –\nit has only a two lists and intentionally avoids the more advanced Keystone functionality (like\n[hooks](https://keystonejs.com/docs/guides/hooks), the\n[document field](https://keystonejs.com/docs/guides/document-fields),\n[access control](https://keystonejs.com/docs/guides/access-control), etc.).\nThis has let us organised most of the Keystone code into two files:\n\n* `schema.ts` defines the [Keystone schema](https://keystonejs.com/docs/apis/schema) –\nthe set of lists, fields and relationships on which your Keystone app operates.\n* `keystone.ts` controls the [system configuration](https://keystonejs.com/docs/apis/config) –\nhow Keystone runs and connects to other services, as well as authentication and sessions.\n\nYou'll need to restart the Keystone process before changes made to the source code are reflected in the app.\nTo do so simply stop the process (\u003ckbd\u003eCtrl\u003c/kbd\u003e + \u003ckbd\u003ec\u003c/kbd\u003e) and re-run `yarn dev`.\n\n## Start a New Project\n\nThere are many way of creating a Keystone application.\nYou can install packages manually to create something from scratch (ie. `yarn add @keystone-next/keystone`) or use a guided process like\n[`create-keystone-app`](https://keystonejs.com/docs/walkthroughs/getting-started-with-create-keystone-app).\nAlternatively, you can copy and modify an existing app like this repo.\n\nTo do so, [fork](https://github.com/keystonejs/keystone-6-heroku-example/fork)\nor otherwise copy these files to your own repository then follow the instructions above to\n[setup a local development environment](#develop-locally).\n\nNote, Keystone is usually used as a [headless CMS](https://en.wikipedia.org/wiki/Headless_content_management_system),\nmeaning your users will visit a separate, frontend application or website, which uses the Keystone API behind the scenes.\nThe creation and deployment of this frontend app is beyond the scope of this guide.\n\n### Deployment\n\nHeroku supports a number of [deployment strategies](https://blog.heroku.com/six-strategies-deploy-to-heroku)\nall of which can be used with Keystone.\nYou've already seen the \"Deploy to Heroku\" button above.\nIt's a fun demo but isn't suited for actually developing and repeatedly deploying an application to production.\nHere we'll use the [\"push to deploy\" strategy](https://devcenter.heroku.com/articles/git).\nThis process uses the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli)\nto create and configure a new app then git to deploy changes.\n\nFirst, ensure you have the Heroku CLI installed and authenticated to your Heroku account.\nIf you're on MacOS the suggested method is Homebrew (for other platforms, see the [download options](https://devcenter.heroku.com/articles/heroku-cli#download-and-install)):\n\n```sh\n# Get the Heroku cli (if you don't have it already)\nbrew tap heroku/brew \u0026\u0026 brew install heroku\n\n# Follow the prompts to authenticate\nheroku auth:login\n```\n\nOnce the CLI tooling is authenticated, run these commands from the root of your app repo.\nYou'll need to replace `my-keystone-app` with a key that will identify you app.\nThis will be used to identify your app later and must be globally unique.\n\n```sh\n# Create the new app and configure a free postgres addon\n# This also adds a git remote to your repo called \"heroku\"\nheroku create my-keystone-app --addons=heroku-postgresql:hobby-dev\n\n# Adding a SESSION_SECRET env var will allow sessions to persist between dyno restarts and deploys\nheroku config:set SESSION_SECRET=$(head -c50 /dev/urandom | base64 | tr -dc 'A-Za-z0-9' | head -c50)\n\n# Deploy your latest commit by pushing the main branch to the heroku remote\ngit push heroku main\n```\n\nIt'll take a few minutes to build and deploy, then your app will appear online.\nThe last section of the build output will give you the public URL, similar to this:\n\n```\nremote: -----\u003e Launching...\nremote:        Released v1\nremote:        https://my-keystone-app.herokuapp.com/ deployed to Heroku\n```\n\n### Migrations\n\nIf you're developing an app, sooner or later, you're going to need to change the database structure.\n\nThe first time you ran `yarn dev` on your dev machine Keystone created a database and setup the initial schema\nby applying the SQL in the `/migrations/20210825070616_initial_schema` directory.\nThis migration was generated by Keystone based on the contents of `schema.ts`.\nYou can leverage this same functionality to create your own migrations.\n\nFor example, lets open `schema.ts` and add a `phone` field to the Person list, like this:\n\n```js\nPerson: list({\n  fields: {\n    name: text({ isRequired: true }),\n    phone: text(),  // \u003c- New!\n\n    // Existing fields ...\n  },\n});\n```\n\nRe-running `yarn dev` will prompt us to create and apply a migration representing this change:\n\n```\n✨ There has been a change to your Keystone schema that requires a migration\n✔ Name of migration … adding phone numbers\n✨ A migration has been created at migrations/20210825230709_adding_phone_numbers\n✔ Would you like to apply this migration? … yes\n✅ The migration has been applied\n```\n\nBehind the scenes, this magic is being performed by\n[Prisma](https://www.prisma.io) and [Prisma Migrate](https://www.prisma.io/docs/concepts/components/prisma-migrate).\nThe resultant SQL (in `/migrations`) can be committed to git like any other file.\nOnce it's applied, your database, GraphQL schema and Admin UI will all reflect the updated list schema.\n\nThis codebase is setup to automatically applied outstanding migrations as part of the build process executed by Heroku.\nYou can see this in `package.json` – the `build` script is `keystone-next build \u0026\u0026 keystone-next prisma migrate deploy`.\n\nIn practise this means database changes are run against your Heroku database a short time before the new version of the application is rolled out.\nAs such, you should ensure your database changes are backwards compatible with the previous release of your app (or risk runtime errors while the deployments are occurring).\n\nThere are many strategies for deploying and coordinating app updates and migrations.\nThe approach we've taken here is simple and works sufficiently well for this infrastructure setup but your app may have different needs.\nSee the [CLI docs](https://keystonejs.com/docs/guides/cli) for the underlying commands used.\n\n### Next Steps\n\nFor ideas on what's possible with Keystone,\nsee the [guides](https://keystonejs.com/docs/guides) section of the website,\ncheckout the [roadmap](https://keystonejs.com/updates/roadmap) and\nstay tuned to the project [updates](https://keystonejs.com/updates).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeystonejs%2Fkeystone-6-heroku-example","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkeystonejs%2Fkeystone-6-heroku-example","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkeystonejs%2Fkeystone-6-heroku-example/lists"}