

Development Setup

This guide describes how to run Slicknode locally for development and testing purposes.

Requirements

You need to have a recent version of Docker as well as NodeJS installed on your computer to complete this guide.

Initialize Project

If you are creating a new project from scratch, initialize a new Slicknode project:

npx slicknode init

Setup Dependent Services

Slicknode needs at the minimum a PostgreSQL database to run. If you also want to use the file or the image module, you need an S3 compatible storage server to store the assets. For the local development setup, we will be using docker-compose so we can have a fully local setup that does not require any network connections.

In your project root directory create a new file docker-compose.yml and add the following content:

docker-compose.yml

version: '3.0'

volumes:
  db_data: {}
  file_storage: {}

services:
  # S3 service to store the assets
  s3:
    image: minio/minio
    ports:
      - '9000:9000'
    command: minio server /export
    environment:
      - MINIO_ACCESS_KEY=fake_access
      - MINIO_SECRET_KEY=fake_secret
    volumes:
      - file_storage:/data

  # PostgreSQL database service
  postgres:
    image: postgres
    ports:
      - '5432:5432'
    volumes:
      - db_data:/var/lib/postgresql/data
    environment:
      - POSTGRES_PASSWORD=mysecretpassword
      - POSTGRES_USER=postgres
      - POSTGRES_DB=master

  # Service to initialize the storage buckets in the S3 service
  s3_init:
    image: minio/mc:latest
    depends_on:
      - s3
    entrypoint: >
      /bin/sh -c "
      sleep 5 &&
      mc alias set minio http://s3:9000 fake_access fake_secret --api S3v4 &&
      mc mb minio/upload || true &&
      mc mb minio/publicupload || true &&
      mc mb minio/image || true &&
      mc policy set download minio/publicupload || true &&
      mc policy set download minio/image || true &&
      exit 0
      "

To start the database and asset services, launch the docker containers:

docker-compose up

Environment Variables

We can set environment variables to configure the service endpoints, ports and credentials for Slicknode. The environment variables can also be configured via a .env file.

Create a file .env in your project root directory and add the following content.

.env

# Database configuration
SLICKNODE_DATABASE_URL=postgresql://postgres:mysecretpassword@localhost:5432/master

SLICKNODE_PORT=3000

# Image handler configuration
SLICKNODE_S3_IMAGE_ENDPOINT=http://localhost:9000
SLICKNODE_S3_IMAGE_ENDPOINT_CDN=http://localhost:3000/images
SLICKNODE_S3_IMAGE_BUCKET=image
SLICKNODE_IMAGE_THUMBNAIL_SECRET=12345678901234567890

SLICKNODE_S3_AWS_ACCESS_KEY_ID=fake_access
SLICKNODE_S3_AWS_SECRET_ACCESS_KEY=fake_secret

For a full list of environment variables that can be used to configure Slicknode, see the docs of the slicknode start command.

Info

The credentials and hosts need to match the settings in the docker-compose.yml file and the exmaple values assume that Docker binds your containers to your localhost network interface. If you changed the credentials or if your docker containers are bound to another host, adjust the values accordingly.

Setup Scripts

If your project does not have a package.json file yet, initialize the package:

npm init -y

Then add slicknode as a dependency to the project so that you can manage the version of Slicknode independently of the Slicknode version you are using globally on your computer:

npm install slicknode

Now we can add a few scripts to your package.json file:

package.json

{
  "scripts": {
    "start": "slicknode start",
    "migrate": "slicknode migrate",
    "dev": "slicknode start --watch --force-migrate"
    //...
  },
  "dependencies": {
    "slicknode": "^0.13.0"
    //...
  }
  //...
}

dev

Start Slicknode in development mode:

npm run dev

It automatically watches for schema and code changes and updates the GraphQL API automatically without restart.

Warning

The --force-migrate option applies the migrations automatically without warning, including deleting tables etc. This is great for fast development, but not recommended to run with a database that has any valuable data in it. If you want to review all migrations before they are applied to the database, remove the flag and execute the npm run migrate script manually.

migrate

Apply the database migrations with all pending schema changes:

npm run migrate

This will show you the pending database migrations and ask for your confirmation. If you want to apply the migrations directly without confirmation, for example in a CI environment, add the --force flag:

npm run migrate -- --force

start

Start the Slicknode GraphQL API in production mode:

npm run start