How to deploy KeystoneJS if we're not a DevOps master?

[maximelebreton]

Hello,

I'm a front-end developer, and I'm very dumped about KeystoneJS for deployment in production.

I install and run KeystoneJS locally with the starter and everything works as excepted, easy and without issue.
But now I want to deploy it online, on Netlify or Now.sh, and I just don't understand why it's so complicated, and the documentation is really not helpful for guys who're not DevOps! (and I hope you want Keystone to be more accessible?)

So here are my steps, as a front-end developer (with no background with back-end stuff):

I tried the build and start on netlify, it doesn't works: Build exceeded maximum allowed runtime

Netlify error

I tried build and start on now.sh, and it doesn't works: Task XXX is stuck in BUILDING for 2700000ms

Now.sh error

So I tried the Docker way as in the documentation:

Dockerfile

(https://www.keystonejs.com/guides/deployment):
Dockerfile
# https://docs.docker.com/samples/library/node/
ARG NODE_VERSION=12.10.0
# https://github.com/Yelp/dumb-init/releases
ARG DUMB_INIT_VERSION=1.2.2

# Build container
FROM node:${NODE_VERSION}-alpine AS build
ARG DUMB_INIT_VERSION

WORKDIR /home/node

RUN apk add --no-cache build-base python2 yarn && \
    wget -O dumb-init -q https://github.com/Yelp/dumb-init/releases/download/v${DUMB_INIT_VERSION}/dumb-init_${DUMB_INIT_VERSION}_amd64 && \
    chmod +x dumb-init
ADD . /home/node
RUN yarn install && yarn build && yarn cache clean

# Runtime container
FROM node:${NODE_VERSION}-alpine

WORKDIR /home/node

COPY --from=build /home/node /home/node

EXPOSE 3000
CMD ["./dumb-init", "yarn", "start"]  

And then: docker build -t my-image .

And first, the Docker image was built with success, but I had this warning about peer dependencies:

Peer dependencies warning

But when I tried to run it: docker run --rm -p 127.0.0.1:3000:3000 my-image:latest
I have this error: There are no Admin UI build artifacts. Please run keystone build before running keystone start

Keystone Error

And Voilà.
I'm here with my "Keystone fatigue", and I hope there is someone to help me, and improve the Keystone documentation about the deployment phase, because it should be easy / accessible.

Thanks!

[nathsimpson]

Hi Maxime!
I could be wrong here, but as a hosting platform for static sites, I don't believe Netlify if the correct choice.
I recommend using Heroku, as I've hosted a few Keystone projects using that. The more day-to-day Keystone devs might recommend something else though. :) It doesn't look like we have any docs on the website yet to assist with Heroku deployment specifically, but feel free to drop any further questions if you get stuck.

[MadeByMike]

Hey @maximelebreton Thank you so much for taking the time to write this up! One of out biggest challenges is that because Keystone is such an unopinionated framework it's really hard to define a 'standard' deployment path. (although we should try)

The GraphQL API and Keystone Admin should (probably) be deployed to a service like Heroku as it is an express App. This is not going to work on Netlify, although although it can on Now.sh as they can run an express app as a serverless function. Here is an example: https://github.com/mitchellhamilton/keystonejs-now-example

For front-end apps you have the option of deploying a "Keystone App" which is an express middleware. In this situation your front-end and backend live together in one big App. Alternatively you can create a standalone front-end app that consumes the API and you can build and deploy this however you like including in a different repository.

[MadeByMike]

We are going to do more to try and improve the docs and take your experience into account. If you have time how would you feel about contributing to a tutorial from a front-end developers perspective?

[jesstelford]

To actually answer your issue... Looking at your error messages, it appears that something is hanging during the build script. Are you able to run yarn build locally? Does it hang, or does it work?

What is the contents of your package.json? With that we can help debug.

Can you provide a minimum reproduction? Is there a basic setup which you can share publicly which exhibits the same behaviour? That way we can investigate for you.

---

We also have a master issue with links out to various deployment approaches:

#1257

The most applicable to you might be the Heroku ticket which has a rough outline of what to do:

#1265

[raulrpearson]

I'm also having a really difficult time deploying. I'm trying to do it on Heroku. I want to learn how to do it and I'm happy to contribute to the documentation. How shall we go about it?

I can think of several approaches:

• Extending quickstart with deployment instructions. In that vein, why doesn't the keystone-app starter build a deploy-ready project? It seems one would still need to address some of the production readiness checklist items. Most importantly, the session handling.

• Morphing the guides > setup section into a tutorial that covers from yarn init to deployment. Extra points if we find a nice way to cover different stacks/options (MongoDB, Postgres, Redis, Heroku, Digital Ocean, Docker, etc.)

• Adding content to the guides > deployment section. I.e. deploying on Heroku, deploying as a docker image, etc.

What do you think?

[MadeByMike]

We've added a guide on deploying to Heroku: #2598, over time I hope we can add additional guides and tutorials.