npm package: @forgeapp/server
Description: Forge Server is the central server for Forge apps
Latest version: 0.2.0

# Forge Server

Forge Server is the central node used to run your Forge apps.

## Pre-requisites

### Required dependencies

#### Database

Forge Server requires a Postgres database to work. We have tested Forge Server with Postgres versions 11.x and 12.x. Newer versions should work, but we do not plan to support anything older than 11.x.

We are planning to look support additional database options in the future.

#### Node.js

Forge Server is a pure Node.js application. Node.js version 16 or higher is required to run Forge Server.

### Optional dependencies

- [Postmark](https://postmarkapp.com) is used for sending application emails. In the future we may introduce a vendor-agnostic path for sending emails. If a `POSTMARK_API_KEY` environment variable is not provided when running Forge server, emails will not be sent.
- [WorkOS](https://workos.com) is used for SSO, directory sync, and Sign in with Google. If `WORKOS_API_KEY`,`WORKOS_CLIENT_ID`, and `WORKOS_WEBHOOK_SECRET` environment variables are not provided when running Forge Server, these functions will not be available.
- [Slack](https://slack.com) can be used to send notifications via Forge's notify methods. If `SLACK_CLIENT_ID` and `SLACK_CLIENT_SECRET` environment variables are not provided when running Forge Server, notifications cannot be sent via Slack.
- [S3](https://aws.amazon.com/s3/) can be used to support file uploads via Forge's file input methods. If `S3_KEY_ID`,`S3_KEY_SECRET`,`S3_BUCKET`, and `S3_REGION` environment variables are not provided when running Forge Server, file uploads will not function properly.

## Required environment variables

- `APP_URL` is the URL where your Forge Server instance is running. For example: `http://localhost:3000` or `https://example.com`.
- `DATABASE_URL` is the Postgres connection string. It should follow the format `postgresql://username:password@host:port/dbname`.
- `SECRET` is a secret that _you must provide_ for use in encrypting passwords. Any string is valid for this value, but you should use something secure!
- `WSS_API_SECRET` is a secret that _you must provide_. It is used internally by Forge Server for communication between Forge services. Any string is valid for this value, but you should use something secure!
- `AUTH_COOKIE_SECRET` is a secret that _you must provide_ for use in encrypting session cookies. Any string **at least 32 characters in length** is valid for this value, but you should use something secure!

### Ports

Forge Server runs services on ports `3000` and `3033`. The main service runs on `3000`.

## Running Forge Server locally

For development, you may wish to run an instance of Forge Server locally.

1. `npm i -g @forge/server`
2. From the directory where you would like to run Forge Server, create a `.env` file like this:

```
DATABASE_URL=<YOUR DATABASE URL>
SECRET=<YOUR SECRET VALUE>
APP_URL=<YOUR APP URL>
AUTH_COOKIE_SECRET=<YOUR AUTH COOKIE SECRET>
WSS_API_SECRET=<YOUR WSS API SECRET>
```

_Note:_ you don't _need_ to use a `.env` file. As long as the [required variables](#required-environment-variables) are set, you should be good to go.

3. If you _have not_ already setup a database, run `forge-server db-init` to initialize one.
4. Run `forge-server start` to run `forge-server`.
5. 🎉 Visit http://localhost:3000 to access your forge server!

## Running Forge Server in production

Running Forge Server in production is largely the same as running in development. For convenience, we've created a Docker image to make this even easier.

The Forge Server Docker image is: `docker.io/forgeapp/server:latest`.

Important things to know:

- You'll still need to provide all [required environment variables](#required-environment-variables) when running the Forge Server Docker image.

## Connecting to Forge Server from your app

Once your Forge Server instance is up and running, it's trivial to connect to it from your Forge apps. Just add an `endpoint` property pointing to your Forge Server instance to the Forge SDK's constructor. For example:

```js
const forge = new Forge({
  apiKey: process.env.FORGE_KEY,
  endpoint: 'wss://<YOUR FORGE SERVER URL>/websocket', // Don't forget the /websocket path!
})
```

**Note:** if you're running Forge Server locally, this URL will use the insecure `ws://` protocol, _not_ the secure `wss://` version used in production deployments.

## Available forge-server commands

Once you run `npm i -g @forgeapp/server`, the following commands are available:

### `forge-server start`

Starts Forge Server. See above for information on running Forge Server locally or in production.