Ilmo

Requirements

• yarn
• Node v14
• Postgresql 11
• Redis
• (wal2json)

NOT FOR BEGINNERS

We do not advise that you build your own projects on top of this project until you're comfortable with the various tools it uses (Node.js, Fastify, PostgreSQL, GraphQL, PostGraphile, Graphile Worker, Graphile Migrate, TypeScript, React, Urql GraphQL client, GraphQL Code Generator, ESLint, Prettier, Jest, Cypress, etc).

This is an advanced project with deeply integrated tooling across the full stack. The project is called "Starter" because it helps you to start new projects with all these technologies, tools and techniques already in place. If you're not already familiar with these things then you'll probably find the project overwhelming, it is not intended to be your first experience of any of these tools.

If you're just getting started with PostGraphile, before you dive into this project make sure you check out the PostGraphile required knowledge and especially the schema design tutorial. This repository takes a slightly different approach to schema design than the aforementioned tutorial, but it's still an incredibly valuable resource.

Table of contents

• Prerequisites
• Getting Started
• Running
• Docker development
• Production build
• Deploying to Heroku
• License

Prerequisites

You can either work with this project locally (directly on your machine) or use a pre-configured Docker environment. We'll differentiate this in the README with a table like this one:

Local mode	OR	Docker mode
command for local development	or	command for docker-compose development

Be careful not to mix and match Docker-mode vs local-mode for development. You should make a choice and stick to it. (Developing locally but deploying with production.Docker is absolutely fine.)

IMPORTANT: If you choose the Docker mode, be sure to read docker/README.md.

For users of Visual Studio Code (VSCode), a .vscode folder is included with editor settings and debugger settings provided, plus a list of recommended extensions. Should you need it, there is also a .devcontainer folder which enables you to use VSCode's remote containers giving you a local-like development experience whilst still using docker containers.

Local development

Requires:

• Node.js v10+ must be installed (v12 recommended)
• PostgreSQL v10+ server must be available
• pg_dump command must be available (or you can remove this functionality)
• VSCode is recommended, but any editor will do

This software has been developed under Mac and Linux, and should work in a bash environment.

Docker development

Requires:

• docker
• docker-compose
• Ensure you've allocated Docker at least 4GB of RAM; significantly more recommended
  • (Development only, production is much more efficient)

Has been tested on Windows and Linux (Ubuntu 18.04LTS).

Getting started

This project is designed to work with yarn. If you don't have yarn installed, you can install it with npm install -g yarn. The Docker setup already has yarn & npm installed and configured.

To get started, please run:

Local mode	OR	Docker mode
yarn setup	or	export UID; yarn docker setup

This command will lead you through the necessary steps, and create a .env file for you containing your secrets.

NOTE: export UID is really important on Linux Docker hosts, otherwise the files and folders created by Docker will end up owned by root, which is non-optimal. We recommend adding export UID to your ~/.profile or ~/.bashrc or similar so you don't have to remember it.

Do not commit .env to version control!

Running

You can bring up the stack with:

Local mode	OR	Docker mode
yarn start	or	export UID; yarn docker start

After a short period you should be able to load the application at http://localhost:5678

This main command runs a number of tasks:

• uses graphile-migrate to watch themigrations/current.sql file for changes, and automatically runs it against your database when it changes
• watches the TypeScript source code of the server, and compiles it from @app/*/src to @app/*/dist so node/graphile-worker/etc. can run the compiled code directly
• runs the node server (includes PostGraphile and Next.js middleware)
• runs graphile-worker to execute your tasks (e.g. sending emails)
• watches your GraphQL files and your PostGraphile schema for changes and generates your TypeScript React hooks for you automatically, leading to strongly typed code with minimal effort

NOTE: docker compose up server also runs the PostgreSQL server that the system connects to.

You may also choose to develop locally, but use the PostgreSQL server via docker compose up -d db.

Then for development you may need a console; you can open one with:

Local mode	OR	Docker mode
bash	or	export UID; yarn docker bash

To shut everything down:

Local mode	OR	Docker mode
Ctrl-c	or	export UID; yarn docker down

Docker development

Be sure to read docker/README.md.

Building the production docker image

To build the production image, use docker build as shown below. You should supply the ROOT_URL build variable (which will be baked into the client code, so cannot be changed as envvars); if you don't then the defaults will apply (which likely will not be suitable).

To build the worker, pass --target worker instead of the default --target server.

docker build \
  --file ./docker/dockerfiles/Dockerfile.prod \
  --build-arg ROOT_URL="http://localhost:5678" \
  --target server \
  .

When you run the image you must pass it the relevant environmental variables, for example:

docker run --rm -it --init -p 5678:5678 \
  -e SECRET="$SECRET" \
  -e JWT_SECRET="$JWT_SECRET" \
  -e DATABASE_VISITOR="$DATABASE_VISITOR" \
  -e DATABASE_URL="$DATABASE_URL" \
  -e AUTH_DATABASE_URL="$AUTH_DATABASE_URL" \
  docker-image-id-here

Currently if you miss required envvars weird things will happen; we don't currently have environment validation (PRs welcome!).

Production build for local mode

Use yarn run build to generate a production build of the project

MIT License

This is open source software; you may use, modify and distribute it under the terms of the MIT License, see LICENSE.md.