# API action
Source: https://ship.paralect.com/docs/api-reference/api-action



## Overview

**API action** — is HTTP handler that perform database updates and other logic required by the business logic.
Actions should reside in the `/actions` folder within resource.
Usually action is a single file that has meaningful name, e.x. `list`, `get-by-id`, `update-email`.

If action has a lot of logic and require multiple files it needs to be placed into the folder with name of the action and action need to exposed using module pattern (index.ts file).

Direct database updates of the current resource entity are allowed within action.

## Examples

```typescript  theme={null}
import Router from '@koa/router';

import { AppKoaContext } from 'types';

import { validateMiddleware } from 'middlewares';

type GetCompanies = {
  userId: string;
};

async function handler(ctx: AppKoaContext<GetCompanies>) {
  const { userId } = ctx.validatedData; // validatedData is returned by API validator

  ctx.body = {}; // action result sent to the client
}

export default (router: Router) => {
  // see Rest API validator
  router.get('/companies', validateMiddleware(schema), handler);
};
```


# API action validator
Source: https://ship.paralect.com/docs/api-reference/api-action-validator



## Overview

**API action validator** — is an array of functions (think middlewares) that is used to make sure that data sent by client is valid.

## Examples

```typescript  theme={null}
import { z } from 'zod';

import { AppKoaContext, Next } from 'types';
import { EMAIL_REGEX, PASSWORD_REGEX } from 'app-constants';

import { userService } from 'resources/user';

import { validateMiddleware } from 'middlewares';

const schema = z.object({
  firstName: z.string().min(1, 'Please enter fist name.').max(100),
  lastName: z.string().min(1, 'Please enter last name.').max(100),
  email: z.string().regex(EMAIL_REGEX, 'Email format is incorrect.'),
  password: z.string().regex(PASSWORD_REGEX, 'The password format is incorrect'),
});

type ValidatedData = z.infer<typeof schema>;

async function validator(ctx: AppKoaContext<ValidatedData>, next: Next) {
  const { email } = ctx.validatedData;

  const isUserExists = await userService.exists({ email });

  ctx.assertClientError(!isUserExists, {
    email: 'User with this email is already registered',
  });

  await next();
}

async function handler(ctx: AppKoaContext<ValidatedData>) {
  // ...action code
}

export default (router: AppRouter) => {
  router.post('/sign-up', validateMiddleware(schema), validator, handler);
};
```

To pass data from the `validator` to the `handler`, utilize the `ctx.validatedData` object:

```typescript  theme={null}
import { z } from 'zod';

import { AppKoaContext, AppRouter, Next, User } from 'types';
import { EMAIL_REGEX, PASSWORD_REGEX } from 'app-constants';

import { userService } from 'resources/user';

import { validateMiddleware } from 'middlewares';
import { securityUtil } from 'utils';

const schema = z.object({
  email: z.string().regex(EMAIL_REGEX, 'Email format is incorrect.'),
  password: z.string().regex(PASSWORD_REGEX, 'The password format is incorrect'),
});

interface ValidatedData extends z.infer<typeof schema> {
  user: User;
}

async function validator(ctx: AppKoaContext<ValidatedData>, next: Next) {
  const { email, password } = ctx.validatedData;

  const user = await userService.findOne({ email });

  ctx.assertClientError(user && user.passwordHash, {
    credentials: 'The email or password you have entered is invalid',
  });

  const isPasswordMatch = await securityUtil.compareTextWithHash(password, user.passwordHash);

  ctx.assertClientError(isPasswordMatch, {
    credentials: 'The email or password you have entered is invalid',
  });

  ctx.validatedData.user = user;
  await next();
}

async function handler(ctx: AppKoaContext<ValidatedData>) {
  const { user } = ctx.validatedData;

  // ...action code
}

export default (router: AppRouter) => {
  router.post('/sign-in', validateMiddleware(schema), validator, handler);
};
```


# API limitations
Source: https://ship.paralect.com/docs/api-reference/api-limitations

To keep things simple and maintainable we enforce some limitations on the API level. Limitations are more conventions and are not enforced in the code. If followed, they guarantee you can continue ship things quickly even after years of development.

## Resource updates

### Rule

**Every** entity update should stay within a resource folder. Direct database updates are allowed in data services, handlers and actions.

### Explanation

This restriction makes sure that entity updates are not exposed outside the resource. This enables the discoverability of all updates and simplifies resource changes.

## Complex read operations

### Rule

Complex data read operations (e.x. aggregation, complex queries) must be defined in the data service.

### Explanation

Complex operations often require maintenance and need to be edited, when the code (especially data schema) changes. The goal of that rule is to keep all such operations in the data service or near it in a separate file, so it's easy to discover them.

## Predictable file location

### Rule

Put things as close as possible to the place where they are used.

### Explanation

We want to keep things together that belong together and keep them apart if they belong apart. With that rule in mind, every resource has clear boundaries.

## Two data services

### Rule

Two data services can not use each other directly. You may use two services together in actions or (better!) in workflows.

### Explanation

Use of two data services inside each other leads to circular dependencies and unnecessary complexities. We encourage the use of CUD events to protect the boundaries of different resources and services. You can use two services together in the workflow.

## Dependencies relatively to the /src folder

### Rule

Files shoud be required from the current folder or from the root, `../` is not allowed. E.x.:

```typescript  theme={null}
import service from 'resources/user/user.service';
```

### Explanation

This makes it easy to move files around without breaking an app and also much simpler to understand where the actual file is located, compared to something like: `../../user.service`.


# Data service
Source: https://ship.paralect.com/docs/api-reference/data-service



## Overview

**Data Service** — is a layer that has two functions: database updates and domain functions. Database updates encapsulate the logic of updating and reading data in a database (also known as Repository Pattern in DDD). Domain functions use database updates to perform domain changes (e.x. `changeUserEmail`, `updateCredentials`, etc). For simplicity, we break the single responsibility pattern here. Data Service is usually named as `entity.service` (e.x. `user.service`).

## Examples

```typescript  theme={null}
import _ from 'lodash';
import db from 'db';
import constants from 'app.constants';
import schema from './user.schema';
import { User } from './user.types';

const service = db.createService<User>('users', { schema });

async function createInvitationToUser(email: string, companyId: string): Promise<User> {
  // the logic
}

export default Object.assign(service, { 
	createInvitationToUser,
});
```


# Event handler
Source: https://ship.paralect.com/docs/api-reference/event-handler



## Overview

**Event handler** — is a simple function that receives event as an argument and performs required logic. All event handlers should be stored in the /handlers folder within resource. Handler name should include event name e.x. `user.created.handler.ts`. That helps find all places were event is used. Direct database updates of the current resource entity are allowed within handler.

## Examples

```ts  theme={null}
import { eventBus, InMemoryEvent } from '@paralect/node-mongo';

import ioEmitter from 'io-emitter';

import { DATABASE_DOCUMENTS } from 'app-constants';
import { Document } from 'types';

const { DOCUMENTS } = DATABASE_DOCUMENTS;

eventBus.on(`${DOCUMENTS}.created`, (data: InMemoryEvent<Document>) => {
    try {
        const document = data.doc;

        ioEmitter.publishToUser(document.userId, 'document:created', document);
    } catch (error) {
      logger.error(`${DOCUMENTS}.created handler error: ${error}`);
    }
})
```

```ts  theme={null}
import { eventBus, InMemoryEvent } from '@paralect/node-mongo';

import { DATABASE_DOCUMENTS } from 'app-constants';
import { User } from 'types';

const { USERS } = DATABASE_DOCUMENTS;

eventBus.onUpdated(USERS, ['firstName', 'lastName'], (data: InMemoryEvent<User>) => {
    const user = data.doc;
    const fullName = user.lastName ? `${user.firstName} ${user.lastName}` : user.firstName;

    console.log(`User fullName was updated: ${fullName}`)
})
```


# CUD events
Source: https://ship.paralect.com/docs/api-reference/events



## Overview

**CUD events (Create, Update, Delete)** — is a set of events published by `data layer` (`@paralect/node-mongo` npm package). Events are the best solve three main problems:

* nicely update denormalized data (e.x.: use user.created and user.deleted to maintain usersCount field in the company)
* avoid tight coupling between your app entities (e.x. if you need to keep user updates history you can just subscribe to user updates in the history resource vs using history.service inside user.resource and marry user and history)
* they’re the best to integrate with external systems (e.x. events can be published as web hooks and webhooks can power real time Zapier triggers)

## Examples

There are three types of events:

* entity.created event (e.x. user.created)

```typescript  theme={null}
{
  _id: string,
  createdOn: Date,
  type: 'user.created',
  userId: string,
  companyId: string,
  data: {
    object: {}, // user object stored here
  },
};
```

* entity.updated event (e.x. user.updated). We use [diff](https://github.com/flitbit/diff) to calculate the raw difference between previous and current version of updated entity. diff object is too complex and should not be used directly. Instead, fields required by business logic should be exposed via change object e.x. previousUserEmail

```typescript  theme={null}
{
  _id: string,
  createdOn: Date,
  type: 'user.updated',
  userId: string,
  companyId: string,
  data: {
    object: {}, // user object stored here
    diff: {},
    change: {}
  },
};
```

* entity.removed event (e.x. user.removed).

```typescript  theme={null}
{
  _id: string,
  createdOn: Date,
  type: 'user.removed',
  userId: string,
  companyId: string,
  data: {
    object: {}, // user object stored here
  },
};
```


# Middlewares
Source: https://ship.paralect.com/docs/api-reference/middlewares



## Overview

Ship provides two essential middleware utilities for API routes:

* **Rate Limit Middleware** — protects your API endpoints from excessive requests
* **Validate Middleware** — validates incoming request data using Zod schemas

Both middlewares are located in `/api/src/middlewares` and can be imported and applied to any route.

## Rate Limit Middleware

The rate limit middleware protects your API endpoints from abuse by limiting the number of requests a user can make within a specified time window. It automatically uses Redis when available, falling back to in-memory storage for development environments.

### Parameters

The `rateLimitMiddleware` function accepts an options object with the following parameters:

* `limitDuration` (optional) — Time window in seconds. Default: `60` seconds
* `requestsPerDuration` (optional) — Maximum number of requests allowed within the time window. Default: `10`
* `errorMessage` (optional) — Custom error message shown when rate limit is exceeded. Default: `'Looks like you are moving too fast. Retry again in few minutes.'`

### Key Features

* **Automatic Storage Selection**: Uses Redis if `REDIS_URI` is configured, otherwise falls back to in-memory storage
* **User-Specific Limits**: Rate limits are applied per authenticated user (based on `user._id`) or per IP address for unauthenticated requests
* **Response Headers**: Includes rate limit headers in the response for client-side tracking

### Example

```typescript  theme={null}
import Router from '@koa/router';

import { rateLimitMiddleware, validateMiddleware } from 'middlewares';

async function handler(ctx: AppKoaContext) {
  // Your handler logic here
  ctx.body = { success: true };
}

export default (router: Router) => {
  router.post(
    '/send-email',
    rateLimitMiddleware({
      limitDuration: 300, // 5 minutes
      requestsPerDuration: 5, // 5 requests per 5 minutes
      errorMessage: 'Too many emails sent. Please try again later.',
    }),
    validateMiddleware(schema),
    handler,
  );
};
```

### Common Use Cases

* Protecting email sending endpoints
* Rate limiting authentication attempts
* Preventing API abuse on expensive operations
* Throttling public API endpoints

## Validate Middleware

The validate middleware automatically validates incoming request data against a Zod schema. It combines data from request body, files, query parameters, and route parameters into a single validated object.

### How It Works

The middleware validates the following request data:

* **Request body** (`ctx.request.body`)
* **Uploaded files** (`ctx.request.files`)
* **Query parameters** (`ctx.query`)
* **Route parameters** (`ctx.params`)

If validation fails, it automatically throws a `400` error with detailed field-level error messages. If validation succeeds, the validated data is available via `ctx.validatedData`.

### Example

```typescript  theme={null}
import Router from '@koa/router';
import { z } from 'zod';

import { AppKoaContext } from 'types';
import { validateMiddleware } from 'middlewares';

// Define your schema
const schema = z.object({
  email: z.string().email('Email format is incorrect'),
  firstName: z.string().min(1, 'First name is required').max(100),
  lastName: z.string().min(1, 'Last name is required').max(100),
  age: z.number().int().positive().optional(),
});

type CreateUserData = z.infer<typeof schema>;

async function handler(ctx: AppKoaContext<CreateUserData>) {
  // Access validated data
  const { email, firstName, lastName, age } = ctx.validatedData;

  // Your handler logic here
  ctx.body = { email, firstName, lastName, age };
}

export default (router: Router) => {
  router.post('/users', validateMiddleware(schema), handler);
};
```

### Error Response Format

When validation fails, the middleware returns a structured error response with field-specific error messages:

```json  theme={null}
{
  "clientErrors": {
    "email": ["Email format is incorrect"],
    "firstName": ["First name is required"]
  }
}
```


# Overview
Source: https://ship.paralect.com/docs/api-reference/overview



`/api` is a source folder for three independent services:

* API — REST API, entry file is `/api/src/app.ts`
* Migrator — small utility that runs MongoDB migrations, entry file is `/api/src/migrator.ts`
* Scheduler — standalone service, that runs background jobs, entry file is `/api/src/scheduler.ts`

## What is resource?

From the outside world, the resource is a set of REST API endpoints that allow managing a particular business entity (e.x. user). Inside, the resource includes methods to work with the database, business logic, database data, request validation, events and event handlers. Most of the time, a resource has 1 on 1 mapping to the database entity. The resource describes how you can work with any given entity. E.x. User API needs to create new users, edit an existing user, list all users.

## Resource components

A resource represents on REST endpoint and most of the time one database table or collection. The resource usually consists of the following parts:

* [API actions](./api-action). Each action consists of three things: the handler, validator, and route.
* [A data service](./data-service). Typically this service is used to access databases. For simplicity, we mix the data access layer with the domain operations associated with a given entity.
* [Event handlers](./event-handler). Event handlers include any updates that come as a reaction to what happens outside the boundaries of any given entity.
* [Workflows](./workflow). They are essentially updates that require multiple resources to work together. E.x. User Signup is usually a workflow, as it requires to a) create user b) create company 3) create authentication token.
* [Data schema](/package-sharing/schemas). We use [Zod](https://zod.dev/) to define database schemas and validate them in runtime. (we’ve used [Joi](https://joi.dev/) in the past).
* Type definitions. If typescript is used for the project.

The data schemas and type definitions can be found in the `packages` folder. Check out the ["Package sharing" section](/package-sharing/overview) for more information on data sharing.

## Example structure

Here is the resource structure example:

```shell  theme={null}
/resource
  /actions
    get.ts
    create.ts
    ...
  index.ts
  resource.service.ts
  resource.routes.ts
```

## Routing

Ship's API uses a structured routing system built on [Koa](https://koajs.com/) that organizes endpoints into three categories: **public**, **private**, and **admin** routes. All requests pass through global middlewares for authentication, error handling, and request processing.

Learn more about the routing architecture in the [Routing](/api-reference/routing/overview) section.


# Middlewares
Source: https://ship.paralect.com/docs/api-reference/routing/middlewares



## Overview

Ship uses middlewares for authentication, error handling, and request processing. Middlewares are applied in two ways:

* **Global Middlewares** — Run for all routes in a specific order
* **Route-Specific Middlewares** — Applied only to private or admin routes

## Execution Order

```mermaid  theme={null}
sequenceDiagram
    participant Request
    participant Global Middlewares
    participant Auth Middleware
    participant Handler

    Request->>Global Middlewares: 1-5: Process all global middlewares
    Note over Global Middlewares: attachCustomErrors<br/>attachCustomProperties<br/>routeErrorHandler<br/>extractTokens<br/>tryToAttachUser
    Global Middlewares->>Auth Middleware: 6: auth or adminAuth (if needed)
    Auth Middleware->>Handler: 7: Execute route handler
    Handler-->>Request: Response
```

## Global Middlewares

### 1. attachCustomErrors

Adds custom error handling methods to the context (`ctx`).

**Available methods:**

```typescript  theme={null}
// Throw simple error
ctx.throwError('User not found', 404);

// Conditional error
ctx.assertError(user.isActive, 'User account is disabled', 403);

// Field-level validation errors
ctx.throwClientError({
  email: 'Email is required',
  password: 'Password must be at least 8 characters'
});

// Conditional client error
ctx.assertClientError(!existingUser, { email: 'Email already exists' });

// Redirect with error message
ctx.throwGlobalErrorWithRedirect('Authentication failed', 'https://example.com/login');
```

### 2. attachCustomProperties

Initializes `ctx.validatedData = {}` which is later populated by the [validate middleware](/api-reference/middlewares#validate-middleware).

### 3. routeErrorHandler

Catches and formats errors from route handlers. Logs errors with request context and hides sensitive details in production.

**Error response format:**

```json  theme={null}
{
  "errors": {
    "email": ["Email is required"],
    "password": ["Password must be at least 8 characters"]
  }
}
```

### 4. extractTokens

Extracts access tokens from requests and stores in `ctx.state.accessToken`.

**Token sources (checked in order):**

1. `ACCESS_TOKEN` cookie
2. `Authorization: Bearer <token>` header

### 5. tryToAttachUser

Validates the access token and attaches the user to `ctx.state.user` if valid. Also updates the user's last request timestamp.

<Note>
  This middleware doesn't block requests if the token is invalid. Use the `auth` middleware to enforce authentication.
</Note>

## Route-Specific Middlewares

Applied to specific route types for authentication and authorization.

### auth

Ensures user is authenticated by checking if `ctx.state.user` exists. Returns `401` if not authenticated.

**Usage:**

```typescript  theme={null}
app.use(mount('/account', compose([auth, accountRoutes.privateRoutes])));
```

### adminAuth

Validates admin access by checking the `x-admin-key` header against the `ADMIN_KEY` environment variable. Returns `401` if invalid.

**Usage:**

```typescript  theme={null}
app.use(mount('/admin/users', compose([adminAuth, userRoutes.adminRoutes])));
```

**Making admin requests:**

```bash  theme={null}
curl -X GET https://api.example.com/admin/users \
  -H "x-admin-key: your-admin-key-here"
```

## Summary

**Execution order:**

1. `attachCustomErrors` - Adds error methods
2. `attachCustomProperties` - Initializes properties
3. `routeErrorHandler` - Wraps in error handler
4. `extractTokens` - Extracts token from cookie/header
5. `tryToAttachUser` - Validates token, attaches user
6. `auth` or `adminAuth` (if applicable)
7. Route handler

## See Also

* [Routing](/api-reference/routing/overview) - Routing architecture overview
* [Middlewares](/api-reference/middlewares) - Validation and rate limiting
* [API Actions](/api-reference/api-action) - Creating resource endpoints


# Overview
Source: https://ship.paralect.com/docs/api-reference/routing/overview



Ship's API routing system is built on [Koa](https://koajs.com/) and organizes routes into three categories: **public**, **private**, and **admin** routes. All routes pass through global middlewares before reaching their handlers.

## Request Flow

```mermaid  theme={null}
flowchart TD
    A[Incoming Request] --> B[Global Middlewares]
    B --> C{Route Type?}
    C -->|Public| D[Public Routes]
    C -->|Private| E[auth middleware]
    C -->|Admin| F[adminAuth middleware]
    E --> G[Private Routes]
    F --> H[Admin Routes]
    D --> I[Route Handler]
    G --> I
    H --> I
    I --> J[Response]
```

## Route Definition

Routes are defined in `/api/src/routes/index.ts`:

```typescript /api/src/routes/index.ts theme={null}
const defineRoutes = (app: AppKoa) => {
  // Global middlewares (applied to all routes)
  app.use(attachCustomErrors);
  app.use(attachCustomProperties);
  app.use(routeErrorHandler);
  app.use(extractTokens);
  app.use(tryToAttachUser);

  // Route registration
  publicRoutes(app);
  privateRoutes(app);
  adminRoutes(app);
};
```

Global middlewares run for every request. See [Routing Middlewares](/api-reference/routing/middlewares) for details.

## Route Types

### Public Routes

Accessible without authentication. Defined in `/api/src/routes/public.routes.ts`.

**Examples:**

* `GET /health` - Health check
* `POST /account/sign-up` - User registration
* `POST /account/sign-in` - User authentication

### Private Routes

Require user authentication via the `auth` middleware. Defined in `/api/src/routes/private.routes.ts`.

```typescript  theme={null}
// Private routes use auth middleware
app.use(mount('/account', compose([auth, accountRoutes.privateRoutes])));
```

**Examples:**

* `GET /account` - Get current user account
* `PUT /account` - Update user profile
* `GET /users` - List users

### Admin Routes

Require admin authentication via the `adminAuth` middleware (validates `x-admin-key` header). Defined in `/api/src/routes/admin.routes.ts`.

```typescript  theme={null}
// Admin routes use adminAuth middleware
app.use(mount('/admin/users', compose([adminAuth, userRoutes.adminRoutes])));
```

**Examples:**

* `GET /admin/users` - Admin user management
* `PUT /admin/users/:id` - Admin user updates

## Route Mounting

Ship uses two Koa utilities:

* **koa-mount** - Mount routes at a specific path prefix
* **koa-compose** - Compose multiple middlewares together

```typescript  theme={null}
// Mount routes with prefix
app.use(mount('/account', accountRoutes.publicRoutes));

// Compose auth middleware with routes
app.use(mount('/account', compose([auth, accountRoutes.privateRoutes])));
```

## Authentication Flow

```mermaid  theme={null}
sequenceDiagram
    participant Client
    participant extractTokens
    participant tryToAttachUser
    participant auth
    participant Handler

    Client->>extractTokens: Request with token
    extractTokens->>tryToAttachUser: ctx.state.accessToken
    tryToAttachUser->>tryToAttachUser: Validate & find user
    tryToAttachUser->>auth: ctx.state.user (if valid)
    
    alt Private Route
        auth->>auth: Check ctx.state.user
        alt Authenticated
            auth->>Handler: Process request
            Handler->>Client: Response
        else Not Authenticated
            auth->>Client: 401 Unauthorized
        end
    else Public Route
        tryToAttachUser->>Handler: Process request
        Handler->>Client: Response
    end
```

## See Also

* [Routing Middlewares](/api-reference/routing/middlewares) - Global and route-specific middlewares
* [API Actions](/api-reference/api-action) - Creating resource endpoints
* [Middlewares](/api-reference/middlewares) - Validation and rate limiting


# Testing
Source: https://ship.paralect.com/docs/api-reference/testing



## Overview

Tests in Ship applications are **optional by default**. The template excludes testing dependencies to keep it lightweight and focused on rapid development. However, as your project grows in complexity or requires higher reliability, testing becomes essential.

Testing is implemented using the [Jest](https://jestjs.io/) framework and [MongoDB memory server](https://github.com/typegoose/mongodb-memory-server). The setup supports execution in CI/CD pipelines. MongoDB memory server allows connecting to an in-memory MongoDB instance and running integration tests in isolation, ensuring reliable and fast test execution without affecting your production database.

<CardGroup cols={2}>
  <Card title="When to Add Testing" icon="shield-check">
    * Complex and confusing business rules
    * Critical calculations/algorithms
    * Core flows that affect other features
    * Logic reused across the applications
    * Areas with recurring hard bugs
  </Card>

  <Card title="When to Skip Testing" icon="ban">
    * Simple CRUD operations
    * Prototype/MVP development
    * Short-term projects
    * Basic UI components
    * Static content pages
  </Card>
</CardGroup>

## Installation and Setup

### Installing Dependencies

Add the necessary testing packages to your project:

```shell  theme={null}
pnpm add -D --filter=api \
     jest \
     @types/jest \
     ts-jest \
     @shelf/jest-mongodb \
     mongodb-memory-server \
     supertest \
     @types/supertest \
     dotenv
```

### Jest Configuration

Navigate to the root of `apps/api`.

Create configuration file for jest:

```javascript jest.config.js theme={null}
/** @type {import('jest').Config} */
const config = {
  preset: '@shelf/jest-mongodb',
  verbose: true,
  testEnvironment: 'node',
  testMatch: ['**/?(*.)+(spec.ts)'],
  transform: {
    '^.+\\.(ts|tsx)$': ['ts-jest', { useESM: true, diagnostics: false }],
  },
  extensionsToTreatAsEsm: ['.ts', '.tsx'],
  watchPathIgnorePatterns: ['globalConfig'],
  roots: ['<rootDir>'],
  modulePaths: ['src'],
  moduleDirectories: ['node_modules'],
  testTimeout: 10000,
  forceExit: true,
  detectOpenHandles: true,
  setupFiles: ['dotenv/config'],
};

export default config;
```

After, create configuration file for jest-mongodb:

```javascript jest-mongodb-config.js theme={null}
module.exports = {
  mongoURLEnvName: 'MONGO_URI',
  mongodbMemoryServerOptions: {
    binary: {
      version: '8.0.0',
    },
    autoStart: false,
  },
};
```

Jest requires set of environment variables to work properly. Create `.env.test` file in the root of `apps/api` and set the following variables:

```shell .env.test theme={null}
APP_ENV=staging

API_URL=http://localhost:3001
WEB_URL=http://localhost:3002

MONGO_DB_NAME=api-tests
```

### package.json scripts

Add test scripts to your `apps/api/package.json`:

```json apps/api/package.json theme={null}
{
  "scripts": {
    "test": "NODE_OPTIONS=--experimental-vm-modules DOTENV_CONFIG_PATH=.env.test jest --runInBand",
    "test:watch": "NODE_OPTIONS=--experimental-vm-modules DOTENV_CONFIG_PATH=.env.test jest --watch",
    "test:coverage": "NODE_OPTIONS=--experimental-vm-modules DOTENV_CONFIG_PATH=.env.test jest --coverage",
  }
}
```

### Test Structure

Tests should be placed next to the code they are testing inside a `tests/` folder. Use `*.spec.ts` suffixes and standardize by unit type:

* `.action.spec.ts` — for action handler + validator (HTTP via supertest)
* `.service.spec.ts` — for data/service layer
* `.validator.spec.ts` — for standalone schema/validators

#### API resource example

```text  theme={null}
apps/api/src/resources/user/
├── actions/
│   ├── create.ts
│   └── tests/
│       └── create.action.spec.ts
├── user.service.ts
├── user.routes.ts
└── tests/
    ├── user.service.spec.ts
    └── factories/
        └── user.factory.ts
```

#### Utilities

Colocate tests for utility modules. Keep them small and pure (no DB).

Create `tests/` folder inside `utils`

```text  theme={null}
apps/api/src/utils/
├── cookie.util.ts
├── promise.util.ts
├── security.util.ts
└── tests/
    ├── cookie.util.spec.ts
    ├── promise.util.spec.ts
    └── security.util.spec.ts
```

## Testing Examples

### Service Integration Test Example

```typescript user.service.spec.ts theme={null}
import { generateId } from '@paralect/node-mongo';

import { userService } from 'resources/user';

describe('user service', () => {
  beforeEach(async () => await userService.deleteMany({}));

  it('should create user', async () => {
    const mockUser = {
      _id: generateId(),
      firstName: 'John',
      lastName: 'Doe',
      email: 'john.doe@example.com',
      isEmailVerified: false,
    };

    await userService.insertOne(mockUser, { publishEvents: false });

    const insertedUser = await userService.findOne({ _id: mockUser._id });

    expect(insertedUser).not.toBeNull();
    expect(insertedUser?.email).toBe(mockUser.email);
  });

  it('should update user', async () => {
    const user = await userService.insertOne(
      {
        _id: generateId(),
        firstName: 'John',
        lastName: 'Doe',
        email: 'john@example.com',
        isEmailVerified: false,
      },
      { publishEvents: false },
    );

    await userService.updateOne({ _id: user._id }, () => ({ isEmailVerified: true }), { publishEvents: false });

    const updatedUser = await userService.findOne({ _id: user._id });
    expect(updatedUser?.isEmailVerified).toBe(true);
  });
});
```

### API Action Test Example

Test your API endpoints:

```typescript sign-up.action.spec.ts theme={null}
import app from 'app';
import request from 'supertest';

import { tokenService } from 'resources/token';
import { userService } from 'resources/user';

describe('post /account/sign-up', () => {
  beforeEach(async () => await Promise.all([userService.deleteMany({}), tokenService.deleteMany({})]));

  it('should create user with valid data', async () => {
    const userData = {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john.doe@example.com',
      password: 'Password123!',
    };

    await request(app.callback()).post('/account/sign-up').send(userData).expect(204);
  });

  it('should return validation error for invalid email', async () => {
    const userData = {
      firstName: 'John',
      lastName: 'Doe',
      email: 'invalid-email',
      password: 'Password123!',
    };

    await request(app.callback()).post('/account/sign-up').send(userData).expect(400);
  });
});
```

### Testing Utilities

```typescript security.util.spec.ts theme={null}
import { securityUtil } from 'utils';

describe('security utils', () => {
  describe('generateSecureToken', () => {
    it('should generate token of specified length', async () => {
      const token = await securityUtil.generateSecureToken(32);

      expect(token).toHaveLength(32);
      expect(typeof token).toBe('string');
    });
  });

  describe('hashPassword', () => {
    it('should hash password correctly', async () => {
      const password = 'test-password-123';
      const hash = await securityUtil.hashPassword(password);

      expect(hash).not.toBe(password);

      const isValid = await securityUtil.verifyPasswordHash(hash, password);
      expect(isValid).toBe(true);
    });
  });
});
```

## Best Practices

### Test Isolation

Each test should be isolated from the others.

Use `beforeEach` to clean the database before each test.

```typescript  theme={null}
describe('user service', () => {
  beforeEach(async () => {
    // Clean database before each test
    await userService.deleteMany({});
  });
});
```

### Test Naming

Use descriptive test names that explain the expected behavior:

```typescript  theme={null}
// Good
it('should return user data when valid ID is provided', () => {});

// Bad
it('should work', () => {});
```

### Mock External Services

Mock external API calls and services:

```typescript  theme={null}
jest.mock('@aws-sdk/client-s3', () => ({
  S3Client: jest.fn(),
  PutObjectCommand: jest.fn(),
}));
```

***

## title: "Testing"

## Overview

In Ship testing settled through [Jest](https://jestjs.io/) framework and [MongoDB memory server](https://github.com/nodkz/mongodb-memory-server#available-options) with possibility running them in CI/CD pipeline. MongoDB's memory server allows connecting to the MongoDB server and running integration tests isolated.

Tests should be placed in the `tests` directory specified for each resource from the `resources` folder and have next naming format `user.service.spec.ts`.

```markdown apps/api/src/resources/user/tests/user.service.spec.ts theme={null}
resources/
  user/
    tests/
      user.service.spec.ts
```

Run tests and linter.

```shell  theme={null}
pnpm run test
```

Run only tests.

```shell  theme={null}
pnpm run test:unit
```

## Example

```typescript  theme={null}
import { Database } from '@paralect/node-mongo';

import { DATABASE_DOCUMENTS } from 'app-constants';

import { User } from 'types';
import { userSchema } from 'schemas';

const database = new Database(process.env.MONGO_URL as string);

const userService = database.createService<User>(DATABASE_DOCUMENTS.USERS, {
  schemaValidator: (obj) => userSchema.parseAsync(obj),
});

describe('User service', () => {
  beforeAll(async () => {
    await database.connect();
  });

  it('should insert doc to collection', async () => {
    const mockUser = { _id: '12q', name: 'John' };

    await userService.insertOne(mockUser);

    const insertedUser = await userService.findOne({ _id: mockUser._id });

    expect(insertedUser).toEqual(mockUser);
  });

  afterAll(async () => {
    await database.close();
  });
});
```

## GitHub Actions

By default, tests run for each pull request to the `main` branch through the `run-tests.yml` workflow.

```yaml .github/workflows/run-tests.yml theme={null}
name: run-tests

on:
  pull_request:
    branches:
      - main

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [ 16.x ]
    steps:
      - uses: actions/checkout@v2
      - name: Test api using jest
        uses: actions/setup-node@v3
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      - run: npm install
      - run: npm test
```

<Tip>
  To set up pull request rejection if tests failed visit `Settings > Branches` tab in your repository. Then add the branch [protection rule](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/defining-the-mergeability-of-pull-requests/managing-a-branch-protection-rule) "Require status checks to pass before merging".
</Tip>


# Using events
Source: https://ship.paralect.com/docs/api-reference/using-events



We are using events to keep our systems simple and use the [full power of denormalized data in MongoDB.](https://www.mongodb.com/blog/post/6-rules-of-thumb-for-mongodb-schema-design-part-2) Denormalization is a database optimization technique in which we add redundant data to one or more tables. It can help us avoid costly joins in a database. You can find a simple example of this technique below.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/denormalization.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=dbd5278d5c4e908865e922d6d5a2e982" alt="Denormalization" data-og-width="1536" width="1536" data-og-height="1040" height="1040" data-path="images/denormalization.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/denormalization.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=56680ac6d079005ccee2010d1370416e 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/denormalization.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6a59110fb195421566aa13bf912f41b4 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/denormalization.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=319d9c2db9461db5028f239175159e6d 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/denormalization.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=54880f7b09660ea3e002132464c1abb4 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/denormalization.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9becf85188591a0f4297291d018bc618 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/denormalization.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=dc7fde13354bac4ee97899f1df61c90d 2500w" />

The picture below shows the 'events part' of a sample API implementation:
<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/events.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=edddc041e1327578cf339b379ef0d98f" alt="Event handlers" data-og-width="1848" width="1848" data-og-height="1894" height="1894" data-path="images/events.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/events.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=35969e4ba0b1f046e587c6edd90777e9 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/events.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=cdc8001a7819adcf56979ee0de21f512 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/events.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=5272a725bdb3d516125842ad471597f2 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/events.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=71b0bf5c3219448a2aff1e746d1831fd 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/events.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b0bab3eb96ddad7e54070500514bee38 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/events.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=337b4256b7d5ba8cb8cbdf86d753a5a5 2500w" />

In Ship, every resource produces events on create, update and delete database operations. As a result, we have all events in one place and these events describe system behavior. Stripe has [an event for any change](https://stripe.com/docs/api/events/types) that happens in their system. We do pretty much the same.


# Workflow
Source: https://ship.paralect.com/docs/api-reference/workflow



## Overview

`Workflow` — is a complex business operation that requires two or more data services to be used together. If a workflow is simple enough and used only in one place — it can be defined right in the Rest API action. If not — it should be placed into the ‘workflowName.workflow’ file. A most common workflow example is a `signup.workflow` that exposes `createUserAccount` function and used when new user signs up or receive an invite.

## Examples

```typescript  theme={null}
import userService from 'resources/user/user.service';
import companyService from 'resources/company/company.service';

const signup = async ({
  firstName,
  surname,
  email,
}: {
  firstName: string;
  surname: string;
  email: string,
}) : Promise<User> => {
 
  let signedUpUser = null;
  await companyService.withTransaction(async (session: any) => {
    const companyId = companyService.generateId();
    await companyService.create({
      _id: companyId,
      name: '',
    },
    { session });

    signedUpUser = await userService.create({
      _id: userId,
      companyId,
      email,
      firstName,
      surname,
    },
    { session });
  });

  return signedUpUser;
};

export default {
  signup,
};
```


# Architecture
Source: https://ship.paralect.com/docs/architecture

Every technological decision is driven by simplicity. We believe that product used by people is the only reason why technologies exist. Our goal is to help products stand up on their feet without investing too much on early stages.

## Overview

Our technological choices based on the following main tools: [Next.js](https://nextjs.org/), [Tanstack Query](https://tanstack.com/query/latest/), [React Hook Form](https://react-hook-form.com/), [Mantine UI](https://mantine.dev/), [Koa.js](https://koajs.com/), [Socket.IO](https://socket.io/), [MongoDB](https://www.mongodb.com/), [Turborepo](https://turbo.build/repo/docs), [Docker](https://www.docker.com/), [Kubernetes](https://kubernetes.io/), [GitHub Actions](https://github.com/features/actions) and [TypeScript](https://www.typescriptlang.org/).

On a high-level Ship consist of the following parts:

<Card title="Web" icon="browser" iconType="duotone" href="/web/overview" />

<Card title="API" icon="square-terminal" iconType="duotone" href="/api-reference/overview" />

<Card title="Scheduler" icon="calendar" iconType="duotone" href="/scheduler" />

<Card title="Migrator" icon="truck-moving" iconType="duotone" href="/migrator" />

<Card title="Deployment" icon="upload" iconType="duotone" href="/deployment/digital-ocean-apps" />

The image below illustrates the main components and key relationships between them:

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/architecture.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=59a44cb8c8c0f48c5d2503c8a0a5ad9f" alt="" data-og-width="2664" width="2664" data-og-height="1704" height="1704" data-path="images/architecture.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/architecture.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d92f73172d199b86e49a891cc0582495 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/architecture.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=305483296bb3ed08cf64e9a30d3c8a9e 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/architecture.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4d59db3c34785531e5dee2116fedd04b 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/architecture.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=37e2178d3ea645bd1f7d56666cc14a78 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/architecture.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=153eae00a60491574930e3293595aac4 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/architecture.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=303d6a7450a630efea80b5a40ceea14b 2500w" />

## Starting application with Turborepo

To run infra and all services -- just run: `pnpm start` 🚀

### Turborepo: Running infra and services separately

1. Start base infra services in Docker containers:

```bash  theme={null}
pnpm run infra
```

2. Run services with Turborepo

```bash  theme={null}
pnpm turbo-start
```

## Using Ship with Docker

To run infra and all services -- just run: `pnpm run docker` 🚀

### Docker: Running infra and services separately

1. Start base infra services in Docker containers:

```bash  theme={null}
pnpm run infra
```

2. Run services you need:

```bash  theme={null}
./bin/start.sh api web
```

You can also run infra services separately with `./bin/start.sh` bash script.


# Contribution Guide
Source: https://ship.paralect.com/docs/contribution-guide



Thank you for interest in contributing to Ship. Here, you'll find all the necessary information to get started.

## Ways to contribute

* **Fix Ship docs** – fixing issues like bad wording, incomplete information, or missing examples in the documentation.
* **Fix Ship template** - contribute to resolving bugs and enhancing the existing code in current template.
* **Give feedback and suggest improvements** - report bugs through [issues](https://github.com/paralect/ship/issues) or suggest improvements.
* **Share Ship** - share Ship link with everyone how can be interested.

## How to open pull request

1. Fork the [project](https://github.com/paralect/ship/fork).
2. Set up the project locally.
3. Create a new branch from the `main` branch, using a name that describes your changes.
4. Implement your changes and create a commit.
5. Open a pull request.
6. Attach 3 labels:

* "To Review" - indicates that the task is ready for review.
* Functionality type - specify a type (Feature, Bug, or Improvement).
* Edit location - specify the area of modification (docs, create-ship-app, node-mongo or template).

Your pull request will be checked by our team. If everything is well, it will be merged to `main` branch.
If there are suggestions, we'll leave comments and label it "Changes Requested". You'll get an email to let you know.
Once you've implemented the necessary changes, please reattach the "To Review" tag.

## Documentation

We use [Mintlify](https://mintlify.com/) for documentation, located in the `/docs` folder.

The docs are written in [MDX](https://mdxjs.com/) format. Check out the [Github Markdown Guide](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
and [Mintlify documentation](https://mintlify.com/docs/quickstart) to become familiar with this syntax.

### How to run documentation

1. Install Mintlify globally.

<Warning>
  Ensure that your Node.js version is 19.00.0 or higher.
</Warning>

<CodeGroup>
  ```shell pnpm theme={null}
  pnpm add -g mint
  ```

  ```shell npm theme={null}
  npm i -g mint
  ```
</CodeGroup>

2. Execute the following command in the project's root directory:

<CodeGroup>
  ```shell pnpm theme={null}
  pnpm run docs
  ```

  ```shell npm theme={null}
  npm run docs
  ```
</CodeGroup>

Documentation will be opened on [http://localhost:4100](http://localhost:4100) if it's not in use.

## Packages

Within the `/package` folder, you'll find two essential packages: `create-ship-app` and `node-mongo`.

**create-ship-app** is simple CLI tool for bootstrapping Ship applications. Downloads actual template from Ship monorepo and configures it to run.
Learn more in the [documentation](/packages/create-ship-app.mdx).

**node-mongo** is lightweight reactive extension to official Node.js MongoDB [driver](https://mongodb.github.io/node-mongodb-native/4.10/).
It's used in the Ship template, and you can find details in the [documentation](/packages/node-mongo.mdx).

## Ship template structure

The project template is in the `/template` folder and includes all necessary files and folders.

Let's explore the structure:

* **.github** - contains scripts for Github actions.
* **.husky** - contains a script that runs before committing and checks for ESLint errors.
* **.vscode** - VS Code settings.
* **apps** - contains [API](/api-reference/overview.mdx) and [WEB](/web/overview.mdx).
* **bin** - contains scripts for setting up and starting the project.
* **packages** - contains packages with shared code. Find more details about package sharing in our [documentation](/package-sharing/overview.mdx).

### How to run Ship template

1. Navigate to the `/template` folder:

```shell  theme={null}
cd template
```

2. In `/apps/api`, copy the **.env.example** file with the name **.env**.

3. Install dependencies:

```shell  theme={null}
pnpm i
```

4. Set up and start project

```shell  theme={null}
pnpm run start
```

The **API** will work on port 3001, **WEB** on port 3002, and **Mailer** on port 4000.

### Deployment

Ship can be deployed on four platforms: **AWS**, **Digital Ocean Kubernetes**, **Digital Ocean Apps**, and **Render**. Deployment settings are in the `/deploy` folder within the respective folders.

When installing a project via `npx create-ship-app`, users can choose the deployment type, and the appropriate settings from the respective folder will be added to their project in the `/deploy` folder.

To check deployment, create a new project via `npx create-ship-app` and attempt to deploy the app in your environment using the  [deployment instructions](/deployment).


# Digital Ocean Apps
Source: https://ship.paralect.com/docs/deployment/digital-ocean-apps



There is a simplified deployment type without Kubernetes. This type is **recommended** for most new applications because it allows you to set up infrastructure faster and doesn't require additional DevOps knowledge from the development team. You can switch to a more complex Kubernetes solution when your application will be at scale.

<Tip>
  Explore our method of deploying Ship to DigitalOcean Apps using [Infrastructure as Code](https://www.pulumi.com/what-is/what-is-infrastructure-as-code/).
  For a detailed guide, check out our [documentation on this approach](/deployment/digital-ocean-apps-iac).
</Tip>

It's a step-by-step Ship deployment guide. We will use the [Digital Ocean Apps](https://www.digitalocean.com/products/app-platform) and [GitHub Actions](https://github.com/features/actions) for automated deployment. [Mongo Atlas](https://www.mongodb.com/) and [Redis Cloud](https://redis.com/try-free/) for databases deployment, and [Cloudflare](https://www.cloudflare.com/) for DNS and SSL configuration.

You need to create [GitHub](https://github.com/), [Digital Ocean](https://www.digitalocean.com/), [CloudFlare](https://www.cloudflare.com/), [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) and [Redis Cloud](https://redis.com/try-free/) accounts.

Also, you need [git](https://git-scm.com/) and [Node.js](https://nodejs.org/en/) if you already haven't.

<Note>
  [Migrator](/migrator) and [Scheduler](/scheduler) will run in a Docker container for API. Unlike [Kubernetes](https://github.com/docs/deployment/kubernetes/digital-ocean.md), where separate containers are used for them.
</Note>

## Setup project

First, initialize your project. Type `npx create-ship-app init` in the terminal then choose desired build type and **Digital Ocean Apps** as a cloud service provider.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b8dd3d65c41aac6cc96db19ef72637ac" alt="Init project" data-og-width="739" width="739" data-og-height="748" height="748" data-path="images/init-project.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1d4182a699988dcdc7a062792ed64a55 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f11b56dd940643183fb357af5deb5055 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=800d987b87f99226ed191324417de1e1 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a0f335955aa56a7c66000bff6c225ad1 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6de7c05d7d4ed5cba27cb7d9d157f797 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=220330c4c1229776bc2ccd165003c646 2500w" />

You will have next project structure.

```shell  theme={null}
/my-app
  /apps
    /web
    /api
  /.github
  ...
```

Create GitHub private repository and upload source code.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=99e9c308e537fa2147b9a42e45851b4a" alt="Private repo" data-og-width="3024" width="3024" data-og-height="1664" height="1664" data-path="images/private-repo.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e4ecbcae9fda0642835e99276f5d9f12 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a8a1cb981e3d6c45105bd096c2ce796d 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8d01a82b9505310b75ad01933948c685 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=46ab1ec791c8127191b7f9a3ec9d5fc1 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b862abab96dbd5d5d779bbe3d1bd126d 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7c5a2c11bcc2bbee9888c41a7a72d3f6 2500w" />

```shell  theme={null}
cd my-app
git remote add origin https://github.com/Oigen43/my-app.git
git branch -M main
git push -u origin main
```

## MongoDB Atlas

Navigate to [MongoDB Atlas](https://cloud.mongodb.com/), sign in to your account and create a new database.

### Database creation

1. Select the appropriate type. Dedicated for a production environment, shared for staging/demo.
2. Select provider and region. We recommend selecting the same or closest region to the DO application.
3. Select cluster tier. Free M0 Sandbox should be enough for staging/demo environments. For production environment we recommended selecting the option that supports cloud backups, M2 or higher.
4. Enter cluster name

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8b72ad717dd384775352d370f925afb1" alt="Mongo cluster" data-og-width="893" width="893" data-og-height="683" height="683" data-path="images/mongo-create.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a5cb583512963f07931ef3f20c50118e 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=deb9a3ba46b6d9967730d1339ebc08ad 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8083ea5e764bd486f0c19a9b19d08d99 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=543a9128c203186f679d31fc2deeb129 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=008b31a0cdf4f7db5ba7736a8cbb8431 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=07a0029145d6b6f87a4d8a413ef332cd 2500w" />

### Security and connection

After cluster creation, you'll need to set up security. Select the authentication type (username and password) and create a user.

<Warning>
  Please be aware that the initial character of the generated password should be a letter. If it isn't, you'll need to create a new password.
  Failing to do this may lead to DigitalOcean parsing the `MONGO_URI` variable incorrectly.
</Warning>

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9ce4c8b83b1b0f6d30908b1b7605ca0d" alt="Mongo setup authentication" data-og-width="859" width="859" data-og-height="665" height="665" data-path="images/mongo-create-password.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c1d296cc086cd97af1574b45379ac3ad 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=629e743c08f46ac2df1d0d0fd374d424 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ad4c9cd34242488aae734458bbe440c3 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dce96660ecfab2cd3b02a8e3b8980544 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1363cfda4a95ef6e29e2dee6e51b8972 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d6ce7c34e39a8e2f31796443faa56f2a 2500w" />

Add IP addresses list, which should have access to your cluster. Add 0.0.0.0/0 IP address to allow anyone with credentials to connect.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dec3cc10f4b5d050c3849a864940d685" alt="Mongo setup ip white list" data-og-width="798" width="798" data-og-height="585" height="585" data-path="images/mongo-create-ip-list.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=663c69bd75770aabe21d1e7f96f608c0 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=25d510ef958fd0dca57a43b6f1a9d6db 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1c0689de96ed85b87290b66325087586 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6afaa4b615e6d1100bc65a8830f0a50c 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=78dde2e2b1c6ea5be3691e2db6d2e76c 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=acd0558df150e379f6ff611e22a09ba8 2500w" />

After database creation, go to the dashboard page and get the URI connection string by pressing the `connect` button.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ec62e0bc9535069f0515855ca5e8e734" alt="Mongo dashboard" data-og-width="2159" width="2159" data-og-height="718" height="718" data-path="images/mongo-dashboard.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e992cb11e0d3a88209a2e6c1e5a8a65f 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5775bf0eca9bab58fe8e2d7a009b9662 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d9f67c142d420322426817ce95d8288c 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b647872fe6b4bfeb4c9b71f33bb568e7 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e0e54fade38da1dc5341fba2ae045d1a 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1c5d112ee9e3c51016f671e1cc7869e0 2500w" />

Select `Connect your application` option. Choose driver and mongo version, and copy connection string. Don't forget to replace `<password>` with your credentials.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=253397af19c0b6c843df2ef8a8df1e3d" alt="Mongo connect dialog" data-og-width="794" width="794" data-og-height="637" height="637" data-path="images/mongo-connection-string.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2b664b7a181fa57766b811d5a43b8d36 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d6aaa543aa485159c1906a2c58cbc30d 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=13637478ce4f5cee86a06ee7109f6a81 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dbf4f374a54d08235f795ff479283aaa 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=92ded21ee9fa5863e3eb92a21def4129 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6bb309ff6dd6630f310453bba784d44c 2500w" />

Save this value. It will be needed later when creating the app in Digital Ocean.

<Tip>
  Before moving to production, it's crucial to set up [MongoDB backup methods](https://www.mongodb.com/docs/manual/core/backups).

  This ensures that you can reliably restore your data in the event of unforeseen circumstances.
</Tip>

## Redis Cloud

Navigate to [Redis Cloud](https://redis.com/try-free/) and create an account. Select cloud provider and region, then press `Let's start free` to finish database creation.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a45dc74ec5ef9ab0fe1dba7e41b0cbf3" alt="Redis create database" data-og-width="953" width="953" data-og-height="581" height="581" data-path="images/redis-creation.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cf9a6246b47174257951e211f4afa9f3 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=20d53d657a6ba50efa8ec8f8a38fe246 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=182fdc95562f4e368d543bed1fe7a5b1 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bc7a420704e9c4806c3041027cb4b9e2 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=801bdbebeeb5b53696a6099154fd0165 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f4e6ca180d429b459bb359bd3f223238 2500w" />

Open database settings and get the database public endpoint and password.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c9ea4f3ceed66d3150be43660aed728f" alt="Redis public endpoint" data-og-width="1601" width="1601" data-og-height="923" height="923" data-path="images/redis-public-endpoint.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6736ef62451c2e29c7c2ced3090cf88d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b9ec666b310ea81856c00606c1639b0e 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=69ddea5ec61e3c8a18b7704e9afda803 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1b7c34de212de19adee67847bda32714 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f36719c6398e4831c3bbac12c7f86e66 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=af0e88e8f8b908430160cad3b0d39cd2 2500w" />
<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1914c1c31a6028b74820e10b3151da03" alt="Redis password" data-og-width="1573" width="1573" data-og-height="514" height="514" data-path="images/redis-password.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8031fef2cf9a78f1a614ccea80009544 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=2d06233dd94d077d88c83a58a819cfb0 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4eaa284a0b7fbd6383d4a77b474bdd04 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c0665f2cbaab668e8b475f75c70e0258 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=872a0beeb86ffe94ec83b1de255bd907 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=73ec7e82a1786104d664c32e64c83fb0 2500w" />

Form Redis connection string using public endpoint and password `redis://:<password@<public-endpoint>`. Save this value. It will be needed later when creating the app in Digital Ocean.

## Digital Ocean

Navigate to the Digital Ocean Control Panel and select the **Apps** tab. The `Full-Stack` build type requires 2 applications. First for [Web](/web/overview) and second for [API](/api-reference/overview), [Migrator](https://github.com/docs/migrator.md), and [Scheduler](https://github.com/docs/scheduler.md) services.

### Initial step

1. Select GitHub as a service provider. You might need to grant Digital Ocean access to your GitHub account or organization.
2. Select the repository with the application.
3. Select a branch for deployment.
4. Select the source directory if the code is in a subfolder.It should `apps/web` for web application and `apps/api` for api.
5. Turn off the Autodeploy option. The Ship uses GitHub Actions for CI due to the poor support of monorepos in the Digital Ocean Apps

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a36b63f3aa9bea9752427e2710fb31d8" alt="Create app screen" data-og-width="1213" width="1213" data-og-height="1171" height="1171" data-path="images/do-create-app.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=258f5ca8d94ae7fed87ef91bbde5af8a 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ca2b570297a509081ccc2f6355e1ec81 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=911dce97d5fb6808d35d3bfcb237b870 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=69f34ac41bc567465dc9e6d5ece83e02 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1c9e5a2dbd65a9c17255edc2d6a92137 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d007c04a5ff939cf1c0714fe3265e184 2500w" />

### Resources setup

1. Delete duplicated resources without dockerfile if you have one.
2. Select desired plan. For staging/demo environments, sufficiently selecting a basic plan for 5\$. For production, you might consider selecting a more expensive plan.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-2.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ac5ad7f32b4dc3ec49f4a7865fe6b0b8" alt="Create app resources" data-og-width="1219" width="1219" data-og-height="781" height="781" data-path="images/do-create-app-step-2.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-2.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9eede7242e30d1075e34b682cd7230c9 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-2.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3f7b476bc405f12cfc02ddb0f346485e 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-2.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=05514a9604cd63c8e472ced51f85eaaf 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-2.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4de118c313b14685adf0600ee3974cb7 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-2.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b1a03f2f88e0951865a9c82c2fcae568 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-2.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=258da01c421ea080a6b059cfb89c4e69 2500w" />

### Environment variables

The `APP_ENV` environment variable is typically set based on the environment in which the application is running.
Its value corresponds to the specific environment, such as "development", "staging" or "production".
This variable helps the application identify its current environment and load the corresponding configuration.

For the web application, by setting the environment variable `APP_ENV`,
the application can determine the environment in which it is running and download the appropriate configuration file:

| APP\_ENV    | File             |
| ----------- | ---------------- |
| development | .env.development |
| staging     | .env.staging     |
| production  | .env.production  |

These files should contain specific configuration variables required for each environment.

In contrast, the API utilizes a single `.env` file that houses its environment-specific configuration.
This file typically contains variables like API keys, secrets, or other sensitive information.
To ensure security, it's crucial to add the `.env` file to the `.gitignore` file,
preventing it from being tracked and committed to the repository.

So just specify the environment variables that will contain the values of your secrets.
For example, if you have a secret named `API_KEY`,
create an environment variable named `API_KEY` and set the value of the corresponding secret for it

Variables, added in the `Global` section will be available to all resources within the application, while ones added in the `ship` section will be available only for that resource. Adding `MONGO_CONNECTION` in the global section allows you to use it later if you decide to set up migrator/scheduler resources

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-3.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2d4e2d17c1761b315a4f2e12b7d32135" alt="Create app environment variables" data-og-width="1207" width="1207" data-og-height="1213" height="1213" data-path="images/do-create-app-step-3.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-3.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=effd7c7c88aee61ab4c5263a1b6a691e 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-3.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=be768a8fd2eae96a2a41da50ae4d88b2 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-3.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=416dbe6924b18dc77c1efa8adbe3d283 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-3.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=881b63d8cba4a541517b218c59fa038d 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-3.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1c113a876a29212715eb629eb1fb2a1d 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-3.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7adb05bf7647217df6bf43e00e76653b 2500w" />

### Application name and hosted region

* \[**Optional**] Select desired application name and/or region for your application

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-4.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=049bb812c567bd93d292084fd199c2d0" alt="Create app host" data-og-width="1223" width="1223" data-og-height="760" height="760" data-path="images/do-create-app-step-4.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-4.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a45d619edef5580ed1dbb049540aa810 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-4.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2ea3e6a35bf46cbe92bcb4332e86dacc 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-4.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b1ee81028f1033b539e1af699a0cdb4a 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-4.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=74f9568539f011a9c13309143b47a592 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-4.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=eca13708c97cf7e572b89f2b0f109ed5 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-app-step-4.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dc0b1ed02f53257cf2d3acbe163acf7a 2500w" />

### Review

Verify everything is correct and create a new resource.

After the application creation, you'll land on the application dashboard page. On dashboard, you can see application status, check runtime logs, track deployment status, and manage application settings.

### App Spec

Digital Ocean sets the path to Dockerfiles to the root by default. You will need to change it manually.
Navigate to Settings, expand the App spec tab and change `dockerfile_path` in the editor.

To deploy your application in a monorepo, it's essential to modify the `source_dir` parameter to the root directory.
This adjustment is necessary to ensure the correct configuration and operation of the applications within the monorepo.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-settings-app-spec.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=baf08be526b34a2485397face655ebcd" alt="Create app review" data-og-width="2296" width="2296" data-og-height="1378" height="1378" data-path="images/do-settings-app-spec.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-settings-app-spec.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c556498ae90c3c1007acc4e04c2d3ef5 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-settings-app-spec.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2565ba04cc6f8836291bad4993b4b8e8 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-settings-app-spec.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=aedd1cfbec92b9a9db5ff3ed8ccdbba9 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-settings-app-spec.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=94908b09cd407fffa752c4c0c46e693f 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-settings-app-spec.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fb9d5c14b7ee932a5209b36006e57ee3 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-settings-app-spec.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1f985d4052939e5b50e63ba1c3b8909f 2500w" />

## Cloudflare

Before this step you need to register a domain name, usually we already have it if not, look: [Register a new domain](https://developers.cloudflare.com/registrar/get-started/register-domain)

Navigate to your Digital ocean application and open `Settings` tab. Select `Domains` row to open domain settings and click `Add domain` button

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-domains.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2d910dfc0242da084289febdd7a66280" alt="Digital Ocean domains" data-og-width="1260" width="1260" data-og-height="890" height="890" data-path="images/do-domains.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-domains.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c53bf9c616de43c8c2ae5efe96acbbcb 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-domains.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=001f84d56f67acfc07cee37a445c34a7 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-domains.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9ad58cd9b0fb7472b9f71577d3711559 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-domains.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0225f799e5d6a6735bcefa49e5f24064 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-domains.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d3822d35b79d0e35368d3fac0fc42d5d 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-domains.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ca8ae58c419f53a679d9a03be99b45f1 2500w" />

Type your desired domain and select option `You manage your domain`

In the bottom section you'll be asked to copy CNAME alias of your digital ocean application name to record in your dns provider.
Copy that alias and leave the form (do no close it or submit).

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-new-domain.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=355fe3893378350db0cee9214a10b302" alt="Digital Ocean new domain" data-og-width="1008" width="1008" data-og-height="921" height="921" data-path="images/do-new-domain.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-new-domain.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1b184b20a1839847b1525c4a61885ce2 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-new-domain.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4e25044da21adab41b35cbd575964e47 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-new-domain.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c1088386f657b537d33015b5d78d69f3 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-new-domain.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=460bcedc10747bc9b1281fd5bca2facf 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-new-domain.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=8509c6ffcad88987e2f09c27bfe5eb35 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-new-domain.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b9fc77e6096f38b32049d6e658b6fd75 2500w" />

Navigate to [CloudFlare](https://dash.cloudflare.com/) and sign into account.

1. Go to `DNS` tab and create a new record.
2. Click `Add record`. Select type `CNAME`,  enter domain name (must be the same you entered in digital ocean settings) and paste alias into `target` field.
   Make sure `Proxy status` toggle enabled.
3. Save changes

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=08d922180734e89d7f207cc1e53db0c0" alt="Cloudflare DNS" data-og-width="1043" width="1043" data-og-height="404" height="404" data-path="images/cloudflare-create-dns.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3e237d626ff7561a6305aecb33448503 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a48bad79c35960051f73b412bcd6a7e8 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=af2348ab864e9eeaa00be967413840eb 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1505fd68486c555e5d905c6b8be7cba0 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1874692f2b2b54c74d94691a0149e3da 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=78e79c338d255f96f57a0acf59d8446b 2500w" />

Now go back to digital ocean and submit form. It usually takes about 5 minutes for digital ocean to confirm and start using your new domain.
Once domain is confirmed, application can be accessed by new address.

## GitHub Actions

You can find two github actions in the `.github/workflows` folder, responsible for triggering deployment when you push changes in your repository. If you chose frontend or backend on the initialization step, you'll have one github workflow for the selected application type.

These actions require a Digital Ocean access token and application ID. Respectively these are `DO_ACCESS_TOKEN` and `DO_API_STAGING_APP_ID`/`DO_WEB_STAGING_APP_ID`/`DO_API_PRODUCTION_APP_ID`/`DO_WEB_PRODUCTION_APP_ID`.

Navigate to digital ocean and open the **API** tab on the left sidebar.
Click **Generate new token**, select a name and set the expiration period.
Also, pick both **read** and **write** permissions for the scope.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-create.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=98e28f15c104309727caefc9cf8eab99" alt="Do access token create" data-og-width="1813" width="1813" data-og-height="561" height="561" data-path="images/do-access-token-create.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-create.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f802a6da3f06642ebb45d87716a303d1 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-create.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ede8867c133e44fc354e898c6125b13e 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-create.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0766d1c939f940d9275a5474ef1762af 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-create.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=531bd53e66c212899d8a506f56d5e83e 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-create.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=350f3f9d3f8d4bbe5cefefa14dd17b87 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-create.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ee5632ba755f08c41e33a85cf5b4311a 2500w" />

You'll see generated token in the list. Do not forget to copy the value and store it in a safe place. You won't be able to copy value after leaving the page.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-copy.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=42c16aecebe4f6dad0cfc8892aef94e9" alt="Do access token copy" data-og-width="1809" width="1809" data-og-height="637" height="637" data-path="images/do-access-token-copy.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-copy.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4ea939bdb49c341623e87b014c954181 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-copy.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b27cb2ab1a4c6c91cb91531ded5e76e6 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-copy.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9aafe7d1b12af4955002511d96e2b499 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-copy.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1aea0a20eea8aa94eebf2bc06dec6ad8 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-copy.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ee8d1542bd8b898f343fdf9c6cf355d7 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-access-token-copy.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c293f27efd632fb368e0e6286051c689 2500w" />

Next, navigate to the **Apps** tab in the left sidebar and open your Digital Ocean application. You can find the id of your application id in the browser address bar.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0b475c34404e66865d8196e2473df358" alt="Do application id" data-og-width="2293" width="2293" data-og-height="726" height="726" data-path="images/do-application-id.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ef6908c26b24ea5f619fc1226e5ed821 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a6d632cd84e49aa988e17d6d446afb9b 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fe9c6b6001b8424fb233746e30a6dd6f 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=50c188de150d97654d8e71ccdfbb8469 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=127a0dab8b741f7632216dc4e79efc33 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dd246b254d5b4433c8d9d52b29ce5fb0 2500w" />

Now you can add these keys to your github repository's secrets.

Navigate to the GitHub repository page, and open the **Settings** tab and these values. You have to be repository **admin** or **owner** to open this tab.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b4161e1be3970b5b8f5f01220318e359" alt="Github secrets" data-og-width="1418" width="1418" data-og-height="922" height="922" data-path="images/github-secrets.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d714786a74aa69040c5a33942ec7af4e 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fe68b6384c41f802beb97f008bfe1e96 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f6e9f7b6e40aa6bf344f4420776dd9ae 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4564a7526a3f51d0750b68dd32545f32 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=917c6cd5ba5f5a0ca3f54c1be5a8f771 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=8d8c7ea519dc513387cadac864794671 2500w" />

Done! Application deployed and can be accessed by provided domain.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f712611f5b52dfcce754a24229ab08d6" alt="Deployed application" data-og-width="1134" width="1134" data-og-height="705" height="705" data-path="images/deployed-application.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=30644cf7b4f0d87a9acc418d9cf02e4e 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=63e05d87b3730edc3b6e76cd0fb5f346 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e603e6f0c01ff13c88a6b7892882b04f 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1429d28b89ebff3caed8a92c6611b240 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=351362539cb9b1ceffa17fc017bf68ba 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3e7b1c9374a2a9b67241c7575718e2c2 2500w" />

## Set up migrator and scheduler (Optional)

Digital Ocean Apps allows configuring additional resources within one application, which can serve as background workers and jobs, and a scheduler to run before/after the deployment process.

Navigate to your Digital Ocean application. **Make sure to select the application with API server**, open a `Create` dropdown menu in the top-right corner, and select the `Create Resources From Source Code` option.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ddcaf8e09d7584f7bb36bb1d880b3a15" alt="Do create resource" data-og-width="1153" width="1153" data-og-height="588" height="588" data-path="images/do-create-resource.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4e61142da7620814f460832d57eaac86 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b15e07b5efb976750fb595e529dc3e1c 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bf2b6ace8447ca67c02b1fa41a8b6201 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c28f95fae06a517473f4e50172272ed0 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=df4ec0a8d3a1134b371cb613527f20d7 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c37a59f74156b25a5bc1b33778536bea 2500w" />

1. Select a project repository, add a path to the source directory, disable auto-deploy, and press `Next`.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-form.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3479c9f580f0c10d20712e7e3b84c516" alt="Create resource screen" data-og-width="900" width="900" data-og-height="1124" height="1124" data-path="images/do-resource-form.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-form.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=94908bb99be27c7d3b82924b639daea7 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-form.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c081ba519101687d106d1e0697931ce8 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-form.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a84615b8a3b58269866832b581434778 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-form.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c9e4efcd3e88e2333ad75cbe5e9bb220 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-form.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7d6ba112c15e504cc7f31678b0f1905b 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-form.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e66d264682309e4aba14bad8d1ddc16f 2500w" />

2. Delete a resource without Dockerfile and edit second by clicking on the pencil icon.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource-step-2.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2e6802b4ab3e7cd252f65bf596920c21" alt="Create app resources" data-og-width="1219" width="1219" data-og-height="781" height="781" data-path="images/do-create-resource-step-2.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource-step-2.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7713005e86ce745ee97b9b78879e22db 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource-step-2.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=67f97b11e47276238bb94ddeb735e66e 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource-step-2.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=76af43ceeb60cb2f034c56486e2f37ad 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource-step-2.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fd8e9c8159d4142e82e6ef9cc15f459c 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource-step-2.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=5e247e8138b27ef179b39a03b19dbb07 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-resource-step-2.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4532ef29367b92b6154eb49549173312 2500w" />

3. In the edit resource form, select `Resource Type` - `Job`, `Before every deploy`, and change the name of the resource (not required, but might be useful later). Press save and go back to the resources screen.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d3aad21ff7a7de1d53cbc0862a7f8342" alt="Edit resource screen" data-og-width="866" width="866" data-og-height="1114" height="1114" data-path="images/do-resource-type.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d67c527294702e33b932dea398cf8347 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=13d107ef2d6700e86fbe00fc2579238d 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=37157e6b0e612b30e050123d814aa452 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=5eee127b3236e0af9dd71e79953dd72b 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=8e7fcbc2564ef5af0513f1876ab43fcc 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=db655ad51f2b9ad2a5b6253ccf0a466c 2500w" />

4. Select the `Add Additional Resource from Source` option below the list of added resources, repeat steps 1-2, and navigate to the edit form for a new resource.

5. Select `Resource Type` - `Worker`, save changes and go back.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type-2.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c483a5fcc2ad56c974900416312a591b" alt="Edit resource screen" data-og-width="865" width="865" data-og-height="519" height="519" data-path="images/do-resource-type-2.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type-2.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6ba42be36ae1513f62c4a3cc0f984ad2 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type-2.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6a0a8a7766f92a065e5ae4666261602b 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type-2.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3925f9f457b345f41404afb972a3b8ef 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type-2.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c268fdd3c9bec8973bcf6604b0a5ae8d 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type-2.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b6ac3f782b12749af54770d66b50eeed 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resource-type-2.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=253f1b90bb0436708438e2a1182a836f 2500w" />

6. Proceed with the next steps, add environment variables if needed, verify a new monthly cost of the application and create resources.

You can find created resources in the `overview` tab.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resources-overview.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c1a9e6f5e4cbab662f3b113d141366b9" alt="Resources overview screen" data-og-width="1207" width="1207" data-og-height="635" height="635" data-path="images/do-resources-overview.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resources-overview.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9aa4b58d17b1837a3fe9a96c882c993e 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resources-overview.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=19e79a4132f954a308c57043accef90a 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resources-overview.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=16399c9d6abc92d5379f6404d6583e8f 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resources-overview.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0b1cd5cccd780c9c48f6ecfd3bed89fb 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resources-overview.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e409d2371fd8a5929d4471713f7e03ea 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-resources-overview.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bcb7b7e528b47236b13027c97bb17003 2500w" />

7. Navigate to Application Spec `(settings tab)`. Change the `dockerfile_path` variable to files with migrator and scheduler.
   Migrator is placed in the `jobs` section. You can also find it by name of the resource. The scheduler is placed in the `workers` section.

<Note>
  To deploy your application in a monorepo, it’s essential to modify the `source_dir` parameter to the root directory.
  This adjustment is necessary to ensure the correct configuration and operation of the applications within the monorepo.
</Note>

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-migrator-app-spec.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9ea6ca894747db1110f4531d2a67ac7a" alt="Migrator spec screen" data-og-width="1051" width="1051" data-og-height="599" height="599" data-path="images/do-migrator-app-spec.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-migrator-app-spec.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=11d660fdf61fbe9eedcbbe62961c79d0 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-migrator-app-spec.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=09b1be55f356da6291554af8664b8f81 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-migrator-app-spec.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a51690257eefc8da14e48107888ab42d 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-migrator-app-spec.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9624e5259d1ee9866cdc614d4ef9e657 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-migrator-app-spec.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b8e82153fbfb701b36a062a670eb65bc 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-migrator-app-spec.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a97daf2b53b9e516dd9140d021ce06c1 2500w" />

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-scheduler-app-spec.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ad94adf46e13b639f18552aa31c990de" alt="Scheduler spec screen" data-og-width="1067" width="1067" data-og-height="602" height="602" data-path="images/do-scheduler-app-spec.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-scheduler-app-spec.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=cc663562f3ee6a17148d34f9f088cd8a 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-scheduler-app-spec.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c5f2370bf704af9349aadc3a11c784a1 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-scheduler-app-spec.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6a0013918a01579f4527515817fc9376 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-scheduler-app-spec.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6d21fe1ccbcf9fff175f05d42b3b1e56 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-scheduler-app-spec.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=57348bf92512baecd4f1cd1e4b15e611 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-scheduler-app-spec.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=621f89acfbaffcbffc002ba56275123e 2500w" />

## Logging (optional)

### Build-in

Digital Ocean has built-in logs in raw format. It will gather all data that your apps will produce.
In order to view them, follow these steps:

1. Log in to your Digital Ocean account.
2. Click on the Apps tab in the left-hand navigation menu.
3. Click on the name of the app you want to view the logs for.
4. Click on the Runtime Logs tab in the app dashboard.
5. You will see a list of logs for different components of your app. Click on the component you want to view the logs for.
6. You can filter the logs by time, severity, and component. Use the drop-down menus provided to select your filter criteria.
7. You can also search for specific keywords in the logs by using the search bar at the top of the page.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e9d09591231ea08085e492d963050a68" alt="Runtime built in logs screen" data-og-width="3002" width="3002" data-og-height="1420" height="1420" data-path="images/do-runtime-built-in-logs.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e33acf74a50a0b692844edf4f5581101 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fb54db401cabff655c1bc552b6efb9fc 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d2fba4b8f3598eae9244171b1ff39bbf 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2fe08f731d713749ad1e348187011371 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=14c8dbfb24c48254811265cde72dfaac 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ad0a7c4965a0405b0e816135bbf916c7 2500w" />

### Integrations

Currently, Digital Ocean Apps supports only 3 integrations: [PaperTrail](https://marketplace.digitalocean.com/add-ons/papertrail), [Logtail](https://marketplace.digitalocean.com/add-ons/logtail) and [Datadog](https://www.datadoghq.com/). You can find detailed instructions on how to set up these logs at this [link](https://docs.digitalocean.com/products/app-platform/how-to/forward-logs/).

### Example Integration Logtail

To configure Logtail follow these steps:

1. Create account on Logtail
2. Open Sources on the left sidebar.
3. Create new source by clicking "Connect source" button

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=75371fc2c4acf1c51184925bee934001" alt="Logs Integrations logtail sources" data-og-width="2782" width="2782" data-og-height="1452" height="1452" data-path="images/do-logs-logtail-sources.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2bc8ff602bf2c9e437deae19e3d86940 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=04f4d2e0e54ae69a00d914d7fa24237f 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bd252dcf462f7889f78ebb611c320cff 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bcce1c8400fb3c9b9bacec2cdcddbcf0 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f35953a82175a46ed387f766e7347f93 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2b409b6244a0fb126fac2a99de4b9114 2500w" />

4. Select HTTP source and specify name for this connection

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1417566973048b00fd1e47a6bc8caad9" alt="Logs Integrations Logtail connect" data-og-width="1157" width="1157" data-og-height="637" height="637" data-path="images/do-logs-logtail-connect-source.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=89de8381194b77bd2513743d5f02448d 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c164ab1ad67364e1a7545c6d6af39c9c 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=8bfa07612fb868353fcd2e1083ae1c43 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f2a966dce5a916f10b44578b20c6a436 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=744402cc90bc0af68a80a99b0077212a 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=09cae3e505ae548ee0b07836821cddae 2500w" />

5. Copy source token

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1a90cc7a5f9f868637d11756c8d06fd3" alt="Logs Integrations Logtail token" data-og-width="1203" width="1203" data-og-height="591" height="591" data-path="images/do-logs-logtail-token.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9e78793cc8c89bbad625eac06e0d95eb 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=97af6a550d4a0f48696bdf6113577573 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=090780dd1e4bf47a6d4de3a9c236b88f 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3fa0599001a66073f3716384058b7ada 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=537d1a04e7a7e2e4f516805ab8231d64 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9e73ea89362e2e1acf063d15810b73dd 2500w" />

6. Open Digital Ocean Apps
7. Select Settings tab for your application

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ea084f54ffbc687f72569fd9232bedb4" alt="Logs Integrations Settings" data-og-width="1500" width="1500" data-og-height="540" height="540" data-path="images/do-app-logs-settings.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4bd955b948b0fec2b7bd7b05ea967f9c 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a4b9a171be86f921fdffb731e971b127 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7ca99a9d31cd0871914906cff975aa79 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=052563385a9369a2d4b54abae12eaa57 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=706c03724097b02439d19342245f155c 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7e01d99b5a719f553e3352340f3b424f 2500w" />

8. Select Log Forwarding and then press "Add Destination"

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c8693b31f3ab7b308ebbc62002e4b440" alt="Logs Forwarding" data-og-width="1256" width="1256" data-og-height="248" height="248" data-path="images/do-logs-log-forwarding.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=598df739406b7353ecb615a8e9987879 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=caf8b8704e97308d90c18d568703d076 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=55408715a4aad49184a80e76cc316b3d 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9e43b22a3cbc43b542965ff5bf3cf83b 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=be52137a05c3044a6dd72a09253db140 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=da39d649f368586eba6a986b0c09561f 2500w" />

9. Fill information with token that we retrieved from Logtail

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=95cc282482a69f90cb571e987419a77e" alt="Logs Create Log Forward" data-og-width="794" width="794" data-og-height="749" height="749" data-path="images/do-create-log-forward.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=263c22d57542fd6109997af1803b6cd9 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=edd29e609266465ea84b8cc6a27fba3c 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6d9ec36b8c1791c28633fbe85c089d4a 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=40ccd0cb305181d1f5f173b046423fe8 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=50169fc46b7bd161eb06498ce777d256 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=77fedf528636b022dcda5e0a74d1176e 2500w" />

10. That's it! In couple minutes your app will send the latest logs to Logtail

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=08cbed4c391bdce857972ec3cc17d1c4" alt="Logs Logtail Final View" data-og-width="1216" width="1216" data-og-height="550" height="550" data-path="images/do-logs-logtail-final-view.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=84cb4f37086b8723ecad893bf2f93b3e 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6e4ed5543a85054a6c9f66eb17bbee94 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9eb430e421add0531700c9c089dd0125 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fa168c6b7a73b277269283bd78fde19d 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3092ca16e912b7fb16a4437d8bbe6450 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a33856864565e283275393bf7b054a4c 2500w" />


# Digital Ocean Apps (IaC)
Source: https://ship.paralect.com/docs/deployment/digital-ocean-apps-iac



There is a simplified deployment type without Kubernetes. This type is **recommended** for most new applications because it allows you to set up infrastructure faster and doesn't require additional DevOps knowledge from the development team. You can switch to a more complex Kubernetes solution when your application will be at scale.

It's a step-by-step Ship deployment guide. We will use the [Digital Ocean Apps](https://www.digitalocean.com/products/app-platform) and [GitHub Actions](https://github.com/features/actions) for automated deployment. [Mongo Atlas](https://www.mongodb.com/) and [Redis Cloud](https://redis.com/try-free/) for databases deployment, [Cloudflare](https://www.cloudflare.com/) for DNS and SSL configuration and [Pulumi](https://www.pulumi.com/) for Infrastructure as Code

You need to create [GitHub](https://github.com/), [Digital Ocean](https://www.digitalocean.com/), [CloudFlare](https://www.cloudflare.com/), [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) and [Redis Cloud](https://redis.com/try-free/) accounts.

Also, you need [git](https://git-scm.com/) and [Node.js](https://nodejs.org/en/) if you already haven't.

## Setup project

First, initialize your project. Type `npx create-ship-app init` in the terminal then choose desired build type and **Digital Ocean Apps** as a cloud service provider.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b8dd3d65c41aac6cc96db19ef72637ac" alt="Init project" data-og-width="739" width="739" data-og-height="748" height="748" data-path="images/init-project.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1d4182a699988dcdc7a062792ed64a55 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f11b56dd940643183fb357af5deb5055 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=800d987b87f99226ed191324417de1e1 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a0f335955aa56a7c66000bff6c225ad1 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6de7c05d7d4ed5cba27cb7d9d157f797 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=220330c4c1229776bc2ccd165003c646 2500w" />

You will have the next project structure.

```shell  theme={null}
/my-app
  /deploy
  /apps
    /web
    /api
  /.github
  ...
```

Create GitHub private repository and upload source code.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=99e9c308e537fa2147b9a42e45851b4a" alt="Private repo" data-og-width="3024" width="3024" data-og-height="1664" height="1664" data-path="images/private-repo.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e4ecbcae9fda0642835e99276f5d9f12 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a8a1cb981e3d6c45105bd096c2ce796d 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8d01a82b9505310b75ad01933948c685 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=46ab1ec791c8127191b7f9a3ec9d5fc1 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b862abab96dbd5d5d779bbe3d1bd126d 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7c5a2c11bcc2bbee9888c41a7a72d3f6 2500w" />

```shell  theme={null}
cd my-app
git remote add origin https://github.com/Oigen43/my-app.git
git branch -M main
git push -u origin main
```

## MongoDB Atlas

Navigate to [MongoDB Atlas](https://cloud.mongodb.com/), sign in to your account and create a new database.

### Database creation

1. Select the appropriate type. Dedicated for a production environment, shared for staging/demo.
2. Select provider and region. We recommend selecting the same or closest region to the DO application.
3. Select cluster tier. Free M0 Sandbox should be enough for staging/demo environments. For production environment we recommended selecting the option that supports cloud backups, M10 or higher.
4. Enter cluster name

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8b72ad717dd384775352d370f925afb1" alt="Mongo cluster" data-og-width="893" width="893" data-og-height="683" height="683" data-path="images/mongo-create.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a5cb583512963f07931ef3f20c50118e 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=deb9a3ba46b6d9967730d1339ebc08ad 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8083ea5e764bd486f0c19a9b19d08d99 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=543a9128c203186f679d31fc2deeb129 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=008b31a0cdf4f7db5ba7736a8cbb8431 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=07a0029145d6b6f87a4d8a413ef332cd 2500w" />

### Security and connection

After cluster creation, you'll need to set up security. Select the authentication type (username and password) and create a user.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9ce4c8b83b1b0f6d30908b1b7605ca0d" alt="Mongo setup authentication" data-og-width="859" width="859" data-og-height="665" height="665" data-path="images/mongo-create-password.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c1d296cc086cd97af1574b45379ac3ad 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=629e743c08f46ac2df1d0d0fd374d424 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ad4c9cd34242488aae734458bbe440c3 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dce96660ecfab2cd3b02a8e3b8980544 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1363cfda4a95ef6e29e2dee6e51b8972 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d6ce7c34e39a8e2f31796443faa56f2a 2500w" />

Add IP addresses list, which should have access to your cluster. Add 0.0.0.0/0 IP address to allow anyone with credentials to connect.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dec3cc10f4b5d050c3849a864940d685" alt="Mongo setup ip white list" data-og-width="798" width="798" data-og-height="585" height="585" data-path="images/mongo-create-ip-list.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=663c69bd75770aabe21d1e7f96f608c0 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=25d510ef958fd0dca57a43b6f1a9d6db 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1c0689de96ed85b87290b66325087586 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6afaa4b615e6d1100bc65a8830f0a50c 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=78dde2e2b1c6ea5be3691e2db6d2e76c 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=acd0558df150e379f6ff611e22a09ba8 2500w" />

After database creation, go to the dashboard page and get the URI connection string by pressing the `connect` button.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ec62e0bc9535069f0515855ca5e8e734" alt="Mongo dashboard" data-og-width="2159" width="2159" data-og-height="718" height="718" data-path="images/mongo-dashboard.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e992cb11e0d3a88209a2e6c1e5a8a65f 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5775bf0eca9bab58fe8e2d7a009b9662 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d9f67c142d420322426817ce95d8288c 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b647872fe6b4bfeb4c9b71f33bb568e7 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e0e54fade38da1dc5341fba2ae045d1a 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1c5d112ee9e3c51016f671e1cc7869e0 2500w" />

Select `Connect your application` option. Choose driver and mongo version, and copy connection string. Don't forget to replace `<password>` with your credentials.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=253397af19c0b6c843df2ef8a8df1e3d" alt="Mongo connect dialog" data-og-width="794" width="794" data-og-height="637" height="637" data-path="images/mongo-connection-string.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2b664b7a181fa57766b811d5a43b8d36 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d6aaa543aa485159c1906a2c58cbc30d 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=13637478ce4f5cee86a06ee7109f6a81 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dbf4f374a54d08235f795ff479283aaa 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=92ded21ee9fa5863e3eb92a21def4129 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6bb309ff6dd6630f310453bba784d44c 2500w" />

Save this value. It will be needed later when creating the app in Digital Ocean.

<Tip>
  Before moving to production, it's crucial to set up [MongoDB backup methods](https://www.mongodb.com/docs/manual/core/backups).

  This ensures that you can reliably restore your data in the event of unforeseen circumstances.
</Tip>

## Redis Cloud

Navigate to [Redis Cloud](https://redis.com/try-free/) and create an account. Select cloud provider and region, then press `Let's start free` to finish database creation.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a45dc74ec5ef9ab0fe1dba7e41b0cbf3" alt="Redis create database" data-og-width="953" width="953" data-og-height="581" height="581" data-path="images/redis-creation.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cf9a6246b47174257951e211f4afa9f3 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=20d53d657a6ba50efa8ec8f8a38fe246 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=182fdc95562f4e368d543bed1fe7a5b1 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bc7a420704e9c4806c3041027cb4b9e2 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=801bdbebeeb5b53696a6099154fd0165 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f4e6ca180d429b459bb359bd3f223238 2500w" />

Open database settings and get the database public endpoint and password.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c9ea4f3ceed66d3150be43660aed728f" alt="Redis public endpoint" data-og-width="1601" width="1601" data-og-height="923" height="923" data-path="images/redis-public-endpoint.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6736ef62451c2e29c7c2ced3090cf88d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b9ec666b310ea81856c00606c1639b0e 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=69ddea5ec61e3c8a18b7704e9afda803 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1b7c34de212de19adee67847bda32714 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f36719c6398e4831c3bbac12c7f86e66 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=af0e88e8f8b908430160cad3b0d39cd2 2500w" />
<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1914c1c31a6028b74820e10b3151da03" alt="Redis password" data-og-width="1573" width="1573" data-og-height="514" height="514" data-path="images/redis-password.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8031fef2cf9a78f1a614ccea80009544 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=2d06233dd94d077d88c83a58a819cfb0 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4eaa284a0b7fbd6383d4a77b474bdd04 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c0665f2cbaab668e8b475f75c70e0258 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=872a0beeb86ffe94ec83b1de255bd907 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=73ec7e82a1786104d664c32e64c83fb0 2500w" />

Form Redis connection string using public endpoint and password `redis://:<password@<public-endpoint>`. Save this value. It will be needed later when creating the app in Digital Ocean.

## Environment variables

The `APP_ENV` environment variable is typically set based on the environment in which the application is running.
Its value corresponds to the specific environment, such as "development", "staging" or "production".
This variable helps the application identify its current environment and load the corresponding configuration.

For the web application, by setting the environment variable `APP_ENV`,
the application can determine the environment in which it is running and download the appropriate configuration file:

| APP\_ENV    | File             |
| ----------- | ---------------- |
| development | .env.development |
| staging     | .env.staging     |
| production  | .env.production  |

These files should contain specific configuration variables required for each environment.

In contrast, the API utilizes a single `.env` file that houses its environment-specific configuration.
This file typically contains variables like API keys, secrets, or other sensitive information.
To ensure security, it's crucial to add the `.env` file to the `.gitignore` file,
preventing it from being tracked and committed to the repository.

So just specify the environment variables that will contain the values of your secrets.
For example, if you have a secret named `API_KEY`,
create an environment variable named `API_KEY` and set the value of the corresponding secret for it.

## Digital Ocean via Pulumi

[Pulumi](https://www.pulumi.com/) is an open-source [Infrastructure as Code (IaC)](https://www.pulumi.com/what-is/what-is-infrastructure-as-code/) platform that allows developers to define and provision cloud infrastructure using familiar programming languages. <br />
Instead of using domain-specific languages or YAML templates, Pulumi leverages existing languages like TypeScript, Python, Go, and C#.

Go to the `/deploy` directory at the root of your project and proceed to the next steps:

<Steps>
  <Step title="Pulumi CLI">
    Ensure you have [Pulumi CLI](https://www.pulumi.com/docs/get-started/install/) installed. <br />
    After installing, verify everything is in working order by running the pulumi CLI:

    ```shell  theme={null}
    pulumi version
    ```
  </Step>

  <Step title="Pulumi Login">
    [Login in pulumi](https://www.pulumi.com/docs/cli/commands/pulumi_login/) for managing your stacks:

    ```shell  theme={null}
    pulumi login --local
    ```
  </Step>

  <Step title="DigitalOcean Tokens and Keys">
    Create your [Personal Access Token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) and [Access Keys](https://docs.digitalocean.com/products/spaces/how-to/manage-access/#access-keys) for DigitalOcean
  </Step>

  <Step title="Configuring Tokens and Keys">
    Add DigitalOcean Personal Access Token and Access Keys to your configuration file: `.zshrc` or `.bashrc`

    First you’ll need to enter the `.zshrc` or `.bashrc` file in editing mode:

    <CodeGroup>
      ```shell .zshrc theme={null}
      vi ~/.zshrc
      ```

      ```shell .bashrc theme={null}
      vi ~/.bashrc
      ```
    </CodeGroup>

    Insert the following variables at the end of the configuration file:

    ```shell  theme={null}
    # DigitalOcean start
    export DIGITALOCEAN_TOKEN=dop_v1_...
    export SPACES_ACCESS_KEY_ID=DO...
    export SPACES_SECRET_ACCESS_KEY=...
    # DigitalOcean end
    ```

    To reflect the changes in the bash, either exit and launch the terminal again.

    Or use the command:

    <CodeGroup>
      ```shell .zshrc theme={null}
      source ~/.zshrc
      ```

      ```shell .bashrc theme={null}
      source ~/.bashrc
      ```
    </CodeGroup>
  </Step>

  <Step title="GitHub apps">
    Grant DigitalOcean access to your GitHub repository using [this link](https://cloud.digitalocean.com/apps/github/install).
  </Step>

  <Step title="Stack initialization">
    Initialize your stack using the command:

    ```shell  theme={null}
    pulumi stack init organization/{project-name}/{environment}
    ```

    Substitute `{project-name}` with the actual name of your project and make sure to update it in `Pulumi.yaml` file. <br />
    Replace `{environment}` with the desired environment: `staging` or `production` values are allowed.
  </Step>

  <Step title="App environments">
    Duplicate the `.env.example` file to create a new environment-specific file using the command:

    <CodeGroup>
      ```shell staging theme={null}
      cp .env.example .env.staging
      ```

      ```shell production theme={null}
      cp .env.example .env.production
      ```
    </CodeGroup>

    Populate the new file with the necessary environment variables.

    <Info>
      Ensure that you set the necessary variables in your web application.
      Edit the .env files accordingly and remember to push these changes to your remote repository.
    </Info>
  </Step>

  <Step title="Installing dependencies">
    Install the required dependencies using the command:

    ```shell  theme={null}
    npm i
    ```
  </Step>

  <Step title="Resources creating">
    To create the resources in the initialized stack, execute the command:

    ```shell  theme={null}
    pulumi up
    ```
  </Step>
</Steps>

Finally, you will observe the following output:

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-preview.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e894db3fcf6dbab2ca47f55191ac6f9f" alt="Pulumi Preview" data-og-width="1326" width="1326" data-og-height="1704" height="1704" data-path="images/do-apps-iac-preview.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-preview.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=5e12e9717a8285cd166f205e3f29f159 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-preview.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a7a4f66590ff7f1bd081eb34a80b5122 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-preview.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6f8ee9aa63dce104824bc7a301cb8eec 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-preview.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f646e79b86fc3fc3695b101fb798991a 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-preview.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=74f312b72bbaaa5ffffb64f5c03b6e56 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-preview.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1bf1721bd31a4469cd624d80bdec37ca 2500w" />

Review the planned resource creation and proceed with the resource update.
This process may take a few minutes to complete.

## Cloudflare

Navigate to your Digital Ocean application and open `Settings` tab.
Navigate to `Domains` row to open domain settings and copy starter domain of application.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-domains.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6b198a397bb6043a363e638323b0e494" alt="Digital Ocean domains" data-og-width="1296" width="1296" data-og-height="670" height="670" data-path="images/do-apps-iac-domains.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-domains.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a0135e39bb0325cf97127acdf9223d1f 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-domains.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=814ff4d38552fb8f9d65d91cc9b87a48 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-domains.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=58f8e751d04cecfa9c218d4c07c944bb 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-domains.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2fc4bb9e4dfd70f765655899f1b89c1e 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-domains.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=5f34baf9cde9ebb8abc61060ba5289e6 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-apps-iac-domains.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=60d48ff5c4cb6ad9e182be4664712efc 2500w" />

Navigate to [CloudFlare](https://dash.cloudflare.com/) and sign into account.

1. Go to `DNS` tab and create a new record.
2. Click `Add record`. Select type `CNAME`,  enter domain name (must be the same you entered in digital ocean settings) and paste alias into `target` field.
   Make sure `Proxy status` toggle enabled.
3. Save changes

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=08d922180734e89d7f207cc1e53db0c0" alt="Cloudflare DNS" data-og-width="1043" width="1043" data-og-height="404" height="404" data-path="images/cloudflare-create-dns.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3e237d626ff7561a6305aecb33448503 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a48bad79c35960051f73b412bcd6a7e8 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=af2348ab864e9eeaa00be967413840eb 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1505fd68486c555e5d905c6b8be7cba0 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1874692f2b2b54c74d94691a0149e3da 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=78e79c338d255f96f57a0acf59d8446b 2500w" />

Now go back to digital ocean and submit form. It usually takes about 5 minutes for digital ocean to confirm and start using your new domain.
Once domain is confirmed, application can be accessed by new address.

## GitHub Actions

You can find two GitHub actions in the `.github/workflows` folder, responsible for triggering deployment when you push changes in your repository. If you chose frontend or backend on the initialization step, you'll have one github workflow for the selected application type.

These actions require a [Digital Ocean Personal Access Token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) and application ID.
Respectively these are `DO_ACCESS_TOKEN` and `DO_API_STAGING_APP_ID`/`DO_WEB_STAGING_APP_ID`/`DO_API_PRODUCTION_APP_ID`/`DO_WEB_PRODUCTION_APP_ID`.

Next, navigate to the **Apps** tab in the left sidebar and open your Digital Ocean application. You can find the id of your application id in the browser address bar.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0b475c34404e66865d8196e2473df358" alt="Do application id" data-og-width="2293" width="2293" data-og-height="726" height="726" data-path="images/do-application-id.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ef6908c26b24ea5f619fc1226e5ed821 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a6d632cd84e49aa988e17d6d446afb9b 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fe9c6b6001b8424fb233746e30a6dd6f 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=50c188de150d97654d8e71ccdfbb8469 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=127a0dab8b741f7632216dc4e79efc33 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-application-id.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dd246b254d5b4433c8d9d52b29ce5fb0 2500w" />

Now you can add these keys to your GitHub repository's secrets.

Navigate to the GitHub repository page, and open the **Settings** tab and these values. You have to be repository **admin** or **owner** to open this tab.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b4161e1be3970b5b8f5f01220318e359" alt="Github secrets" data-og-width="1418" width="1418" data-og-height="922" height="922" data-path="images/github-secrets.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d714786a74aa69040c5a33942ec7af4e 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fe68b6384c41f802beb97f008bfe1e96 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f6e9f7b6e40aa6bf344f4420776dd9ae 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4564a7526a3f51d0750b68dd32545f32 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=917c6cd5ba5f5a0ca3f54c1be5a8f771 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/github-secrets.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=8d8c7ea519dc513387cadac864794671 2500w" />

Done! Application deployed and can be accessed by provided domain.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f712611f5b52dfcce754a24229ab08d6" alt="Deployed application" data-og-width="1134" width="1134" data-og-height="705" height="705" data-path="images/deployed-application.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=30644cf7b4f0d87a9acc418d9cf02e4e 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=63e05d87b3730edc3b6e76cd0fb5f346 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e603e6f0c01ff13c88a6b7892882b04f 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1429d28b89ebff3caed8a92c6611b240 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=351362539cb9b1ceffa17fc017bf68ba 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/deployed-application.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3e7b1c9374a2a9b67241c7575718e2c2 2500w" />

## Logging (optional)

### Build-in

Digital Ocean has built-in logs in raw format. It will gather all data that your apps will produce.
In order to view them, follow these steps:

1. Log in to your Digital Ocean account.
2. Click on the Apps tab in the left-hand navigation menu.
3. Click on the name of the app you want to view the logs for.
4. Click on the Runtime Logs tab in the app dashboard.
5. You will see a list of logs for different components of your app. Click on the component you want to view the logs for.
6. You can filter the logs by time, severity, and component. Use the drop-down menus provided to select your filter criteria.
7. You can also search for specific keywords in the logs by using the search bar at the top of the page.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e9d09591231ea08085e492d963050a68" alt="Runtime built in logs screen" data-og-width="3002" width="3002" data-og-height="1420" height="1420" data-path="images/do-runtime-built-in-logs.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e33acf74a50a0b692844edf4f5581101 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fb54db401cabff655c1bc552b6efb9fc 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d2fba4b8f3598eae9244171b1ff39bbf 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2fe08f731d713749ad1e348187011371 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=14c8dbfb24c48254811265cde72dfaac 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-runtime-built-in-logs.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ad0a7c4965a0405b0e816135bbf916c7 2500w" />

### Integrations

Currently, Digital Ocean Apps supports only 3 integrations: [PaperTrail](https://marketplace.digitalocean.com/add-ons/papertrail), [Logtail](https://marketplace.digitalocean.com/add-ons/logtail) and [Datadog](https://www.datadoghq.com/). You can find detailed instructions on how to set up these logs at this [link](https://docs.digitalocean.com/products/app-platform/how-to/forward-logs/).

### Example Integration Logtail

To configure Logtail follow these steps:

1. Create account on Logtail
2. Open Sources on the left sidebar.
3. Create new source by clicking "Connect source" button

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=75371fc2c4acf1c51184925bee934001" alt="Logs Integrations logtail sources" data-og-width="2782" width="2782" data-og-height="1452" height="1452" data-path="images/do-logs-logtail-sources.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2bc8ff602bf2c9e437deae19e3d86940 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=04f4d2e0e54ae69a00d914d7fa24237f 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bd252dcf462f7889f78ebb611c320cff 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bcce1c8400fb3c9b9bacec2cdcddbcf0 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f35953a82175a46ed387f766e7347f93 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-sources.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2b409b6244a0fb126fac2a99de4b9114 2500w" />

4. Select HTTP source and specify name for this connection

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1417566973048b00fd1e47a6bc8caad9" alt="Logs Integrations Logtail connect" data-og-width="1157" width="1157" data-og-height="637" height="637" data-path="images/do-logs-logtail-connect-source.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=89de8381194b77bd2513743d5f02448d 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c164ab1ad67364e1a7545c6d6af39c9c 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=8bfa07612fb868353fcd2e1083ae1c43 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f2a966dce5a916f10b44578b20c6a436 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=744402cc90bc0af68a80a99b0077212a 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-connect-source.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=09cae3e505ae548ee0b07836821cddae 2500w" />

5. Copy source token

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1a90cc7a5f9f868637d11756c8d06fd3" alt="Logs Integrations Logtail token" data-og-width="1203" width="1203" data-og-height="591" height="591" data-path="images/do-logs-logtail-token.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9e78793cc8c89bbad625eac06e0d95eb 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=97af6a550d4a0f48696bdf6113577573 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=090780dd1e4bf47a6d4de3a9c236b88f 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3fa0599001a66073f3716384058b7ada 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=537d1a04e7a7e2e4f516805ab8231d64 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-token.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9e73ea89362e2e1acf063d15810b73dd 2500w" />

6. Open Digital Ocean Apps
7. Select Settings tab for your application

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ea084f54ffbc687f72569fd9232bedb4" alt="Logs Integrations Settings" data-og-width="1500" width="1500" data-og-height="540" height="540" data-path="images/do-app-logs-settings.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4bd955b948b0fec2b7bd7b05ea967f9c 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a4b9a171be86f921fdffb731e971b127 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7ca99a9d31cd0871914906cff975aa79 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=052563385a9369a2d4b54abae12eaa57 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=706c03724097b02439d19342245f155c 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-app-logs-settings.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7e01d99b5a719f553e3352340f3b424f 2500w" />

8. Select Log Forwarding and then press "Add Destination"

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c8693b31f3ab7b308ebbc62002e4b440" alt="Logs Forwarding" data-og-width="1256" width="1256" data-og-height="248" height="248" data-path="images/do-logs-log-forwarding.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=598df739406b7353ecb615a8e9987879 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=caf8b8704e97308d90c18d568703d076 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=55408715a4aad49184a80e76cc316b3d 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9e43b22a3cbc43b542965ff5bf3cf83b 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=be52137a05c3044a6dd72a09253db140 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-log-forwarding.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=da39d649f368586eba6a986b0c09561f 2500w" />

9. Fill information with token that we retrieved from Logtail

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=95cc282482a69f90cb571e987419a77e" alt="Logs Create Log Forward" data-og-width="794" width="794" data-og-height="749" height="749" data-path="images/do-create-log-forward.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=263c22d57542fd6109997af1803b6cd9 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=edd29e609266465ea84b8cc6a27fba3c 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6d9ec36b8c1791c28633fbe85c089d4a 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=40ccd0cb305181d1f5f173b046423fe8 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=50169fc46b7bd161eb06498ce777d256 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-create-log-forward.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=77fedf528636b022dcda5e0a74d1176e 2500w" />

10. That's it! In couple minutes your app will send the latest logs to Logtail

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=08cbed4c391bdce857972ec3cc17d1c4" alt="Logs Logtail Final View" data-og-width="1216" width="1216" data-og-height="550" height="550" data-path="images/do-logs-logtail-final-view.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=84cb4f37086b8723ecad893bf2f93b3e 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6e4ed5543a85054a6c9f66eb17bbee94 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9eb430e421add0531700c9c089dd0125 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fa168c6b7a73b277269283bd78fde19d 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3092ca16e912b7fb16a4437d8bbe6450 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-logs-logtail-final-view.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a33856864565e283275393bf7b054a4c 2500w" />


# AWS
Source: https://ship.paralect.com/docs/deployment/kubernetes/aws



export const provider_1 = "aws"

export const provider_0 = "aws"

It's a step-by-step Ship deployment guide. We will use [Amazon Elastic Kubernetes Service (EKS)](https://aws.amazon.com/eks), [Mongo Atlas](https://www.mongodb.com/), [Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr), [GitHub Actions](https://github.com/features/actions) for automated deployment, and [CloudFlare](https://www.cloudflare.com) for DNS and SSL configuration.

You need to create [GitHub](https://github.com), [AWS](https://aws.amazon.com), [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) and [CloudFlare](https://www.cloudflare.com/) accounts and install the next tools on your machine before starting:

* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) - CLI tool for accessing Kubernetes cluster;
* [kubectx](https://github.com/ahmetb/kubectx) - CLI tool for easier switching between Kubernetes contexts;
* [helm](https://helm.sh/docs/intro/install) - CLI tool for managing Kubernetes deployments;
* [aws-cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) - CLI tool for managing AWS resources;
* [eksctl](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html) - CLI tool for managing EKS clusters;
* [k8sec](https://github.com/dtan4/k8sec) - CLI tool for managing Kubernetes Secrets easily;

<Accordion title="How to install k8sec on Linux?">
  Download k8sec tar.gz, then do:

  ```
  chmod +x k8sec
  ```

  ```
  sudo cp k8sec /usr/local/bin/
  ```

  ```
  k8sec --help
  ```
</Accordion>

Try the next commands to ensure that everything is installed correctly:

```
kubectl

kubectx

helm

aws sts get-caller-identity

eksctl

k8sec
```

Also, you need [git](https://git-scm.com/) and [Node.js](https://nodejs.org/en/) if you already haven't.

## Setup project

First, initialize your project. Type `npx create-ship-app@latest` in the terminal then choose **AWS EKS** deployment type.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/init-project-aws-eks.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=676c591c5a36437f57780bf0af9bcc22" alt="Init project" data-og-width="2244" width="2244" data-og-height="1492" height="1492" data-path="images/aws/init-project-aws-eks.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/init-project-aws-eks.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=27872a51bb2c2087cc3da6a92bd94f15 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/init-project-aws-eks.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=32374c13821dbd872eb5623023d4b329 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/init-project-aws-eks.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9237edaff30f8a8f9c74b5e58df44c55 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/init-project-aws-eks.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=39dfd4c6408c24102311e2ebad3906e2 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/init-project-aws-eks.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a9288484aaed0c66b5b42b06813f9ddf 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/init-project-aws-eks.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b62cbfcbe9080f70d8e9eecc7394fd11 2500w" />

You will have the next project structure.

```shell  theme={null}
/my-ship-app
  /.github
  /apps
    /api
    /web
  /deploy
  ...
```

## AWS Regions

AWS Regions are physical locations of AWS cluster data centers. Each group of logical data centers calls Availability Zone (AZ). AZs allow the operation of production applications and databases that are more highly available, fault-tolerant and scalable.

Now you need to select an AWS region for future use of the services. You can read more about region selection for your workloads here: [What to Consider when Selecting a Region for your Workloads](https://aws.amazon.com/blogs/architecture/what-to-consider-when-selecting-a-region-for-your-workloads/).

For this deployment guide, we will use the **us-east-1** region.

<Tip>
  Usually, you have to create AWS resources in a single region. If you don't see created resources, you may need to switch to the appropriate AWS region.
</Tip>

## Container registry

You need to create [private repositories](https://console.aws.amazon.com/ecr/private-registry/repositories/create) for storing Docker images. The deployment script will upload images to Container Registry during the build step, and Kubernetes will automatically pull these images from Container Registry to run a new version of the service during the deployment step.

Now we should create a repository for each service.

For Ship, we need to create repositories for the next services:

* [**API**](/api-reference/overview) - api
* [**Migrator**](/migrator) - migrator
* [**Scheduler**](/scheduler) - scheduler
* [**Web**](/web/overview) - web

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-creation.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9f4b30cccea63ec6a42b8084c142836a" alt="Container Registry creation" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/ecr-creation.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-creation.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d7e14d75f042d8ed1f5e43fe3dc8e3c6 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-creation.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7216e5bca0fc362fdd03e0a1b7690897 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-creation.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6bcdfeb47eab0e148081098fb049800f 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-creation.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1fc3260c19583e5f8110bf4f4e4afb3b 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-creation.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=bf765b5d348cdfc6343409737e100e8b 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-creation.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2751ecbba41e146422f793db62bf73d4 2500w" />

<Tip>
  You should create a private repository for each service manually.
</Tip>

After creation, you should have the following 4 services in ECR

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-created.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=fd823dab13d6ee73a858645297a5610e" alt="Container Registry creation" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/ecr-created.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-created.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=27cc66b9f90e6460968fb3e7d1ee6723 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-created.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3c444878b0745e4cced8b33a7870b7c1 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-created.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7ffb4715db8a4cf7ecb0162eef915150 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-created.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=8a9acf3abc5eca082063ad1d6426d10e 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-created.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e422cf954b06d801a1c798911c8d6d78 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ecr-created.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7aeef7e2b199ccb3cf5307140b50445b 2500w" />

Docker images for each service are stored in a separate repository.
During the deployment process script will automatically create paths to repositories in the next format:

* [**API**](/api-reference/overview) - 276472736030.dkr.ecr.us-east-1.amazonaws.com/api;
* [**Migrator**](/migrator) - 276472736030.dkr.ecr.us-east-1.amazonaws.com/migrator;
* [**Scheduler**](/scheduler) - 276472736030.dkr.ecr.us-east-1.amazonaws.com/scheduler;
* [**Web**](/web/overview) - 276472736030.dkr.ecr.us-east-1.amazonaws.com/web;

<Tip>
  Repository name`276472736030.dkr.ecr.us-east-1.amazonaws.com/api` consists of 5 values:

  * `276472736030` - AWS account ID;
  * `us-east-1` - AWS region.
  * `dkr.ecr` - AWS service.
  * `amazonaws.com` - AWS domain.
  * `api` - service name.
</Tip>

<Tip>
  Images for all environments will be uploaded to the same repository for each service.
</Tip>

## Kubernetes Cluster

Now let's [create EKS cluster](https://console.aws.amazon.com/eks/cluster-create).

<Steps>
  <Step title="Select Custom Configuration">
    Navigate to the cluster creation page and choose `Custom configuration` <br />
    Make sure to disable `EKS Auto Mode`

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-configuration-options.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=64f71af1469be4dac9655059a12605bd" alt="Cluster configuration" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/cluster-creation-configuration-options.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-configuration-options.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=28cab7ea1374538d33c7fe62e1d1ab60 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-configuration-options.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4e6bfb83621852343f721552f7fb6da0 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-configuration-options.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a7baca74850c980a7935ea71516789a4 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-configuration-options.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=18cf489102084e08f6b00380cc0f2115 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-configuration-options.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c7a5e3b9cca78e9038fae55552d3ec89 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-configuration-options.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=66cef38bfffc0f380aca8d3090540405 2500w" />
    </Frame>
  </Step>

  <Step title="Name Your Cluster">
    Enter a name for your cluster. It's recommended to use your project name.

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-naming.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9c7154d6025ab02240aecf44d7d42ab1" alt="Cluster naming" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/cluster-creation-naming.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-naming.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4faa31ba86c013cfac14fba74653c128 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-naming.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=bdfa2af7d9f5aab393b6988c3e73ea43 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-naming.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9fc7eb12265fc145a2e849df347f7a85 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-naming.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=820cf39d61a9cd4faaefb004d8c6c19c 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-naming.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0341da3ab3b2daa285120420968d2b02 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-naming.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a34fafe0f3cff1c916d0d325f37bc177 2500w" />
    </Frame>

    <Tip>
      For multi-environment setups, append the environment name to your cluster:

      * `my-ship-app-staging`
      * `my-ship-app-production`
    </Tip>
  </Step>

  <Step title="Configure Cluster IAM Role">
    For the `Cluster IAM role`:

    1. Click the `Create recommended role` button
    2. AWS will automatically create IAM roles with necessary EKS cluster permissions
    3. Return to cluster creation page and select the created policy

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-cluster-iam-role.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7d123bf9dcbc036b6e022acedb757fb1" alt="Cluster IAM role" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/cluster-creation-cluster-iam-role.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-cluster-iam-role.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=5a6df2b36a91678cb2e7f6f1a28f0ae8 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-cluster-iam-role.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f4cb9118d81ef692e20ab7e20f0d530c 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-cluster-iam-role.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7ff669b83f97ae8acdc59897c11698c3 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-cluster-iam-role.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2ecd8582d4043180a390a6c6a9cd7ba3 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-cluster-iam-role.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=8a1d1b7b25f9e873dd8493920b873835 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-cluster-iam-role.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=dfeee445b29bbaa0883d702524a3ae42 2500w" />
    </Frame>
  </Step>

  <Step title="Set Authentication Mode">
    In the `Cluster access` section:

    * Set `Cluster authentication mode` to `EKS API and ConfigMap`

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-access.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=218e340be2f9aa5b0c88bd02c2207e5e" alt="Cluster access" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/cluster-creation-access.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-access.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b433bf1c32f94bc665f277efe5f6cbe2 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-access.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f4c55452f5af6ae2a74cf4537ddc94ed 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-access.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=36513715d2f5b226aea3717c33d7de6a 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-access.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=deb40c5bb19906d5460f24d6d3628d13 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-access.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4ff6e364fde918b4f6ee8774e161b8f1 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-access.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6aed9cacb4bef3bfd760ae0a555fc9be 2500w" />
    </Frame>
  </Step>

  <Step title="Configure Add-ons">
    Navigate to 'Select add-ons' and verify these required add-ons are selected:

    * CoreDNS
    * kube-proxy
    * Amazon VPC CNI
    * Node monitoring agent

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-addons.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f7ca73825aa2e29ae54525d156db7fe6" alt="Cluster addons" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/cluster-creation-addons.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-addons.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e9bd99ada8c5a2fc2ad84422746ce3e3 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-addons.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0881ca51f8c95640de54576d7a78daaa 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-addons.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=44670d05d4d66e06747cfbf49ef8c234 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-addons.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f8acc0e2634a538e3e67a54e402a2b5e 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-addons.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=bd7019be4005dfef3a96125e819741f6 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-creation-addons.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3ea23ada5e743b92b393ea6692ae90f9 2500w" />
    </Frame>
  </Step>

  <Step title="Review and Create">
    Move to the review section and verify all configuration parameters are correct before creating the cluster.

    <Note>
      Default values for other configuration parameters are suitable unless you have specific requirements.
    </Note>
  </Step>
</Steps>

After creation, you need to wait a few minutes until the cluster status becomes **Active**.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-active-state.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b0cea81c0aa58e7692440985ccf03b66" alt="Cluster Created" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/cluster-active-state.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-active-state.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=da22b2615c4d24bb9384b5986418b944 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-active-state.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4e47d7ef58a5ca44bd8b5b27af6011b1 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-active-state.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b8177345921b54294e02285787f2a130 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-active-state.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e1dd3bd6ec3a7d20306dfc5287d84d57 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-active-state.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d485805d894ff302a388614cfc3fd9b2 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-active-state.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3eaa875ff706674316555dfad25ba8be 2500w" />

After cluster creation, you should attach [EC2](https://aws.amazon.com/ec2) instances to the cluster. You can do it by clicking on the **Add Node Group** button on the **Compute** tab.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-computing.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=79bd12b3d076fedc3145cfd6d287b725" alt="Add Node Group" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/cluster-computing.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-computing.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1f68cc9027b6fab7b4f51ca389fdc159 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-computing.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c549e320026b147d973799724fbffa91 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-computing.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=52238c109c31b8fd904b6af0835d6481 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-computing.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=decc11dccf7cac46cea9a284c9ef5c52 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-computing.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=80a25dd39cb785813ced0a0ff8ca1436 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cluster-computing.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=81d6be0a53a0be2548ddda651605f642 2500w" />

Set the node group name as `pool-app` and select the relevant Node IAM role from the list.

If you don't have any IAM roles here, click the `Create recommended role` button. You will be prompted to create properly configured IAM roles with all necessary permissions.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-configuration.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=deaed8460981e2288f9feab408326b04" alt="Node Group Configuration" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/node-group-configuration.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-configuration.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b7d5bd8007e42350771497606c0a6fdf 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-configuration.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1d7b72f5a580bfbe0fd919b32b789a55 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-configuration.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0060514650a874e744aa55a0769c295e 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-configuration.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=37530665bae78d91cfe801b07bb4852f 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-configuration.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=049aba3bc0c744601898966e321961ae 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-configuration.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9bcf70e8bdb24a7a1cc9304d7ed78c13 2500w" />

AWS recommends creating at least 2 nodes **t3.medium** instance type for the production environment.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-instance-configuration.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=38663f70a66162c92109d080c27763ff" alt="Node Group Instance Configuration" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/node-group-instance-configuration.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-instance-configuration.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9a2ac1d9c7584d9b5be4a41dd4ad7fef 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-instance-configuration.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=472dac1c1fd229848c7917b2f7e795ac 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-instance-configuration.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=ee845f337c6e75e09d5ef3c2da6d407b 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-instance-configuration.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=378b5a5f1e5e9ac54c37390a0a99b6b3 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-instance-configuration.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d6028317d3fa61eae0086c1dd4c170b5 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/node-group-instance-configuration.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a457cafa59ea59fb31641a97d4425797 2500w" />

<Note>
  Default values for other configuration parameters are suitable unless you have specific requirements.
</Note>

## Accessing a cluster from a local machine

<Warning>
  Before proceeding, ensure you have [configured the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
</Warning>

<Steps>
  <Step title="Update kubeconfig">
    Run the following command to configure cluster access:

    ```bash  theme={null}
    aws eks update-kubeconfig \
      --region us-east-1 \
      --name my-ship-app \
      --alias my-ship-app
    ```

    <Note>
      Replace `us-east-1` with your cluster's region and `my-ship-app` with your cluster name.
    </Note>
  </Step>

  <Step title="Switch to cluster context">
    Execute `kubectx` in your terminal and select your cluster from the list.

    ```bash  theme={null}
    kubectx
    ```

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/kubectx.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=eae5fae0539142d3d2814aadb80a2eec" alt="Kubectx selection" data-og-width="1564" width="1564" data-og-height="842" height="842" data-path="images/aws/kubectx.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/kubectx.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=845b2a0454fdfe64b2151f2999e5008e 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/kubectx.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b94abd8f81ad4abf8935191e8b06162e 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/kubectx.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6b54ce24dd7b80a55cc17fbf056f8140 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/kubectx.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=cf4e254844d91b1067a9a49f14e77b84 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/kubectx.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9b1083610c31b98526f279c26fe2c785 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/kubectx.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=76225e3637893f55889436a3e1301076 2500w" />
    </Frame>
  </Step>

  <Step title="Verify cluster access">
    Check the installed pods by running:

    ```bash  theme={null}
    kubectl get pods -A
    ```

    You should see a list of system pods in your cluster:

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/pods-list.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=edb31117d0c08b2607f58a4075d56c5a" alt="List of pods" data-og-width="1420" width="1420" data-og-height="966" height="966" data-path="images/aws/pods-list.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/pods-list.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b1ff5c4a118e31178119e83dee4064c7 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/pods-list.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7c0766d2bf3e88bdd19aadc9bc6c9d1f 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/pods-list.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3e9177fbd9a839eb5629b39fe8e4779f 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/pods-list.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a57ad6f7b551dc237cadd6023d4ae421 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/pods-list.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=993664223b99fd0b7bd2a73117e0a009 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/pods-list.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9a29e04e5f4ca3ad73d2de4ad0c84e31 2500w" />
    </Frame>
  </Step>
</Steps>

## Ingress NGINX Controller

[ingress-nginx](https://github.com/kubernetes/ingress-nginx) is an Ingress controller for Kubernetes using [NGINX](https://nginx.org) as a reverse proxy and load balancer.

<Tip>
  Learn more about ingress-nginx functionality in the **[official documentation](https://docs.nginx.com/nginx-ingress-controller/intro/how-nginx-ingress-controller-works/)**.
</Tip>

<Steps>
  <Step title="Navigate to dependencies directory">
    Change to the `deploy/dependencies` directory in your terminal.
  </Step>

  <Step title="Configure Helm Values (Optional)">
    This step is required **only if** you specified a custom node group name in your EKS cluster.

    If you did, update the `eks.amazonaws.com/nodegroup` value in `values.yaml.gotmpl`:

    ```yaml deploy/dependencies/ingress-nginx/values.yaml.gotmpl {5} theme={null}
    controller:
      publishService:
        enabled: true
      nodeSelector:
        eks.amazonaws.com/nodegroup: pool-app

    rbac:
      create: true

    defaultBackend:
      enabled: false
    ```
  </Step>

  <Step title="Install dependencies">
    Install helm dependencies using helmfile:

    ```bash  theme={null}
    helmfile deps
    ```
  </Step>

  <Step title="Review and apply changes">
    Preview the changes first:

    ```bash  theme={null}
    helmfile diff
    ```

    If the preview looks correct, apply the configuration:

    ```bash  theme={null}
    helmfile apply
    ```
  </Step>
</Steps>

## DNS and SSL

<Steps>
  <Step title="Get Load Balancer Address">
    After deploying ingress-nginx, retrieve the Load Balancer's external hostname:

    ```bash  theme={null}
    kubectl get svc ingress-nginx-controller -n ingress-nginx -o json | jq -r '.status.loadBalancer.ingress[0].hostname'
    ```

    <Note>
      If you have trouble running the above command, you can alternatively use:

      ```bash  theme={null}
      kubectl get svc ingress-nginx-controller -n ingress-nginx
      ```

      And copy the value from the `EXTERNAL-IP` column.
    </Note>
  </Step>

  <Step title="Domain Naming Convention">
    You can follow this recommended naming pattern for different environments:

    | Environment | API Domain           | Web Domain           |
    | ----------- | -------------------- | -------------------- |
    | Production  | api.ship.com         | app.ship.com         |
    | Staging     | api.staging.ship.com | app.staging.ship.com |
  </Step>

  <Step title="Configure DNS in Cloudflare">
    1. First, ensure you have a domain in Cloudflare. You can either:

    * [Register a new domain](https://developers.cloudflare.com/registrar/get-started/register-domain/)
    * [Transfer an existing domain](https://developers.cloudflare.com/registrar/get-started/transfer-domain-to-cloudflare/)

    2. In the Cloudflare DNS tab, create 2 `CNAME` records:

    * One for Web interface
    * One for API endpoint

    Both should point to your Load Balancer's external hostname.

    Enable the **Proxied** option to:

    * Route traffic through Cloudflare
    * Generate SSL certificates automatically

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-api.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=8078a01bb59393c8b3f3ba8a7aba49fc" alt="CloudFlare API DNS Configuration" data-og-width="2088" width="2088" data-og-height="905" height="905" data-path="images/aws/cloudflare-api.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-api.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a5d3c23c7940f33ce4102278c20797ba 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-api.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e677ae578143b667420481b622185186 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-api.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=27e50640739273bf1d29af68167e7746 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-api.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f3e59f5221dd65875113762af44ce55d 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-api.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=bdec4233a4c623f7ba09f80c6714d972 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-api.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3244fc386a00f3e04ec7d438f7fac6db 2500w" />
    </Frame>

    <br />

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-web.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2a2d5276f36eca99b49dabb520b56d82" alt="CloudFlare Web DNS Configuration" data-og-width="2101" width="2101" data-og-height="913" height="913" data-path="images/aws/cloudflare-web.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-web.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=50ee873c17149e2fdae5edb79edb68c3 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-web.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=544895640791e23007b67bad2b1f26db 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-web.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a8b2df9ef0b06712953794fc27b9c8a9 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-web.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=473fe9ea571bdb3845fb1609ccc7efee 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-web.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e1dd12bf5a10f5059e38f70f9f28e807 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/cloudflare-web.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e76c855f69d9ffb5e6c3e312e5e5c234 2500w" />
    </Frame>

    <Note>
      Cloudflare's free Universal SSL certificates only cover the apex domain and one subdomain level. For multiple subdomain levels, you'll need an [Advanced Certificate](https://developers.cloudflare.com/ssl/edge-certificates/advanced-certificate-manager/manage-certificates/).
    </Note>
  </Step>

  <Step title="Update Configuration Files">
    Update your domain settings in the appropriate environment configuration files:

    For API service:

    <CodeGroup>
      ```yaml deploy/app/api/production.yaml theme={null}
      service: api
      port: 3001
      domain: api.my-ship-app.paralect.com
      ```

      ```yaml deploy/app/api/staging.yaml theme={null}
      service: api
      port: 3001
      domain: api.my-ship-app.staging.paralect.com
      ```
    </CodeGroup>

    For Web service:

    <CodeGroup>
      ```yaml deploy/app/web/production.yaml theme={null}
      service: web
      port: 3002
      domain: my-ship-app.paralect.com
      ```

      ```yaml deploy/app/web/staging.yaml theme={null}
      service: web
      port: 3002
      domain: my-ship-app.staging.paralect.com
      ```
    </CodeGroup>
  </Step>
</Steps>

## MongoDB Atlas

[MongoDB Atlas](https://cloud.mongodb.com/) is a fully managed cloud database service that provides automated backups, scaling, and security features. It offers 99.995% availability with global deployment options and seamless integration with AWS infrastructure.

### Cluster Creation

<Steps>
  <Step title="Access MongoDB Atlas">
    Sign in to your [MongoDB Atlas account](https://cloud.mongodb.com/) and create a new project if needed.
  </Step>

  <Step title="Deploy New Cluster">
    Click **Create** to start cluster deployment.

    **Cluster Tier Selection:**

    * **Staging**: `M0` (Free tier) - Suitable for development and testing
    * **Production**: `M10` or higher - Includes automated backups and advanced features

    {provider_1 === 'aws' && (
          <div>
            <p><strong>Provider & Region:</strong></p>
            <ul>
              <li>Select <strong>AWS</strong> as your cloud provider</li>
              <li>Choose the <strong>same region</strong> as your EKS cluster for optimal performance</li>
            </ul>
          </div>
        )}

    {provider_1 === 'do' && (
          <div>
            <p><strong>Provider & Region:</strong></p>
            <ul>
              <li>Select <strong>AWS</strong> as your cloud provider</li>
              <li>Choose the <strong>region closest</strong> to your Digital Ocean cluster for optimal performance</li>
            </ul>
          </div>
        )}

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=12e0f3723a43957b09f9f997b5554b63" alt="Deploy MongoDB Atlas cluster" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/deploy-cluster.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cfb12e79df6ea845ffb0aa615434ecf7 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bf5a003fd3a8f3ca4c3ffba6e9ab6db0 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8e2c72357b422c264b20fe7c1fd36075 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cd6b61eb75bf6ef937868c94ac9a421d 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8278428381d14224fd01ed516c514ff9 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=19210f154cfd38dc259adbf5e5c76fd8 2500w" />
    </Frame>
  </Step>

  <Step title="Configure Cluster Name">
    Enter a descriptive cluster name (e.g., `ship-production-cluster`, `ship-staging-cluster`)
  </Step>
</Steps>

### Security Configuration

<Steps>
  <Step title="Create Database User">
    Navigate to **Database Access** → **Add New Database User**

    * **Authentication Method**: Password
    * **Username**: Use environment-specific names (e.g., `api-production`, `api-staging`)
    * **Password**: Generate a strong password
    * **Database User Privileges**: **Read and write to any database**

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d9ba39fe38521e971b70bd34d43ab752" alt="Add MongoDB database user" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/add-database-user.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=68544cba438ccb44c7be67ec7ad5cefb 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f53199d693721e1882126a1496e405e1 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=423f8ddb9c421170db524d2052d43b84 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=860bbd0fba9f718f10eeaa33b3810410 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5ee12fa84f74040e2e08e6ea3cc11917 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8c74692cd49fff030294bde2007e41e4 2500w" />
    </Frame>

    <Warning>
      **Password Requirements**: Ensure the password starts with a letter and contains only alphanumeric characters and common symbols. Special characters at the beginning can cause URI parsing issues.
    </Warning>
  </Step>

  <Step title="Configure Network Access">
    Navigate to **Network Access** → **Add IP Address**

    * Click **Allow access from anywhere** to allow connections from any IP with valid credentials
    * For production, consider restricting to specific IP ranges for enhanced security

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=54cc00ef5fc768a1753dd1335f850cd6" alt="Configure MongoDB network access" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/network-access.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=dccabf32819369c563ab5b165136c694 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4c3c48d8e784535cfe66ddb687b6be70 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8ac03225a4bfd3baa71f89c9bf58e666 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e52ab68ea3d07aeef22a15302fb7b1c6 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d29f40ab52a77e6fd8c34260c0867dbb 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=649aef9f4962561fbf5f1a9355659422 2500w" />
    </Frame>
  </Step>
</Steps>

### Get Connection String

<Steps>
  <Step title="Access Connection Details">
    Go to your cluster dashboard and click the **Connect** button.

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=04932b0500406004a25474f27ec3ff03" alt="MongoDB Atlas dashboard" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/dashboard.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=73196c72d85645c47ed7338771305aa8 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=53e6457f582eb635a10baffab829717b 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=85269ac775d8edf077a4c92811276d2d 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c61bf29216d7982a60109736dc9b8232 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5f3742b38ac3f817d9d5d050be62b5b9 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=3480e0905f009210c0c4252bbba7d7ca 2500w" />
    </Frame>
  </Step>

  <Step title="Copy Connection String">
    1. Select **Drivers** in the "Connect your application" section
    2. Choose **Node.js** driver and latest version
    3. Copy the connection string and replace `<db_password>` with your actual password

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4ecb740161946dfd461a2ba977fe5202" alt="MongoDB connection string" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/cluster-connect.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c323ba15591da81637947314c3045e04 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a407cf450558d2348b27dfc239de8c4c 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ad0eec2c14d3ad3bdba60065bf721576 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b1a23603d2f7cceb667f82c8aafd1b49 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cf9d64963ad407c31f9a085aa2ec49bc 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=886d43dc8551d619cc52a9c522c0e25e 2500w" />
    </Frame>

    **Example Connection String:**

    ```bash  theme={null}
    mongodb+srv://api-production:your-password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
    ```
  </Step>

  <Step title="Save Connection Details">
    Store the connection string securely - you'll need it for environment configuration later
  </Step>
</Steps>

<Tip>
  Before deploying to production, configure [automated backups](https://www.mongodb.com/docs/atlas/backup-restore-cluster/) in the Atlas console to ensure data recovery capabilities.
</Tip>

## Environment variables

Kubernetes applications require proper environment variable configuration for both API and Web components. This section covers how to set up and manage environment variables securely using Kubernetes secrets and configuration files.

### API Environment Variables

For the API deployment, you need to set up environment variables using Kubernetes secrets to securely manage sensitive configuration data.

<Info>
  **Secrets** in Kubernetes are used to store sensitive information, such as passwords, API tokens, and keys.
  They are encoded in Base64 format to provide a level of security.
  These can be mounted into containers as data volumes or used as environment variables.
</Info>

Before deploying the app, make sure all necessary variables from the API config are exist. Here are the minimal set of required variables:

| Name            | Description                | Example value                                      |
| --------------- | -------------------------- | -------------------------------------------------- |
| `APP_ENV`       | Application environment    | `production`                                       |
| `MONGO_URI`     | Database connection string | `mongodb://<username>:<password>@ship.mongodb.net` |
| `MONGO_DB_NAME` | Database name              | `api-production`                                   |
| `API_URL`       | API domain URL             | `https://api.my-ship-app.paralect.com`             |
| `WEB_URL`       | Web app domain URL         | `https://my-ship-app.paralect.com`                 |

#### Environment Variable Details

<Accordion title="APP_ENV">
  Specifies the application environment (development, staging, production). This controls logging levels, debugging features, error reporting, and other environment-specific behaviors. The API uses this to determine which configuration settings to load.
</Accordion>

<Accordion title="MONGO_URI">
  MongoDB connection string including authentication credentials and cluster information. This is the primary database connection for the API. Format: `mongodb+srv://username:password@cluster.mongodb.net`. Each environment should use a separate database cluster or at minimum separate credentials.
</Accordion>

<Accordion title="MONGO_DB_NAME">
  Name of the MongoDB database to use for this environment. Each environment (development, staging, production) should have its own database to prevent data conflicts and ensure proper isolation.
</Accordion>

<Accordion title="API_URL">
  The fully qualified domain name where the API will be accessible. This must be a valid HTTPS URL and should match your Kubernetes ingress configuration. Used for CORS settings and internal service communication.
</Accordion>

<Accordion title="WEB_URL">
  The fully qualified domain name where the web application will be accessible. Used for CORS configuration, redirect URLs, email templates, and social sharing metadata. Must be a valid HTTPS URL.
</Accordion>

#### Setting up Kubernetes Secrets

<Steps>
  <Step title="Create namespaces and secret objects">
    Create Kubernetes namespaces and secret objects for staging and production environments:

    ```bash  theme={null}
    kubectl create namespace staging
    kubectl create secret generic api-staging-secret -n staging
    kubectl create namespace production
    kubectl create secret generic api-production-secret -n production
    ```
  </Step>

  <Step title="Initialize secret storage">
    First, create an `APP_ENV` variable to initialize secret storage for k8sec:

    <CodeGroup>
      ```bash production theme={null}
      k8sec set api-production-secret APP_ENV=production -n production
      ```

      ```bash staging theme={null}
      k8sec set api-staging-secret APP_ENV=staging -n staging
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify secret creation">
    Run the following command to check the created secret:

    <CodeGroup>
      ```bash production theme={null}
      k8sec list api-production-secret -n production
      ```

      ```bash staging theme={null}
      k8sec list api-staging-secret -n staging
      ```
    </CodeGroup>
  </Step>

  <Step title="Prepare environment file">
    Create a `.env.production` file with all required variables:

    <CodeGroup>
      ```bash .env.production theme={null}
      APP_ENV=production
      MONGO_URI=mongodb://username:password@ship.mongodb.net
      MONGO_DB_NAME=api-production
      API_URL=https://api.my-ship-app.paralect.com
      WEB_URL=https://my-ship-app.paralect.com
      ```

      ```bash .env.staging theme={null}
      APP_ENV=staging
      MONGO_URI=mongodb://username:password@ship.mongodb.net
      MONGO_DB_NAME=api-staging
      API_URL=https://api.my-ship-app.staging.paralect.com
      WEB_URL=https://my-ship-app.staging.paralect.com
      ```
    </CodeGroup>

    <Warning>
      Replace all example values with your actual configuration. Never use production secrets in documentation or version control.
    </Warning>
  </Step>

  <Step title="Import secrets to Kubernetes">
    Import secrets from the .env file to Kubernetes secret using k8sec:

    <CodeGroup>
      ```bash production theme={null}
      k8sec load -f .env.production api-production-secret -n production
      ```

      ```bash staging theme={null}
      k8sec load -f .env.staging api-staging-secret -n staging
      ```
    </CodeGroup>
  </Step>
</Steps>

<Warning>
  After updating environment variables, you must initiate a new deployment for changes to take effect.
  Kubernetes pods cache variable values during startup, requiring a pod restart or rolling update to apply changes.
</Warning>

### Web Environment Variables

The web application uses Next.js environment variables that are embedded at build time and made available in the browser. Unlike API secrets, these variables are stored directly in the GitHub repository.

<Info>
  **Why Web Environment Variables Are Safe in Git**: Web environment variables (prefixed with `NEXT_PUBLIC_`) contain only public configuration like URLs and API endpoints. They don't include sensitive data like passwords or API keys, making them safe to store in version control. These values are already exposed to users in the browser, so repository storage doesn't create additional security risks.
</Info>

<Warning>
  **Security Notice**: Never store sensitive information (passwords, API keys, secrets) in web environment files as they will be accessible on the client side. Only use public configuration values that are safe to expose to end users.
</Warning>

#### Configuration Files

Web environment variables are stored in separate files for each deployment environment:

<CodeGroup>
  ```bash apps/web/.env.production theme={null}
  NEXT_PUBLIC_API_URL=https://api.my-ship-app.paralect.com
  NEXT_PUBLIC_WS_URL=https://api.my-ship-app.paralect.com
  NEXT_PUBLIC_WEB_URL=https://my-ship-app.paralect.com
  ```

  ```bash apps/web/.env.staging theme={null}
  NEXT_PUBLIC_API_URL=https://api.my-ship-app.staging.paralect.com
  NEXT_PUBLIC_WS_URL=https://api.my-ship-app.staging.paralect.com
  NEXT_PUBLIC_WEB_URL=https://my-ship-app.staging.paralect.com
  ```
</CodeGroup>

#### Environment Variables Reference

| Variable              | Description                          | Example                                |
| --------------------- | ------------------------------------ | -------------------------------------- |
| `NEXT_PUBLIC_API_URL` | Base URL for API requests            | `https://api.my-ship-app.paralect.com` |
| `NEXT_PUBLIC_WS_URL`  | WebSocket server URL for real-time   | `https://api.my-ship-app.paralect.com` |
| `NEXT_PUBLIC_WEB_URL` | App's own URL for redirects/metadata | `https://my-ship-app.paralect.com`     |

<Tip>
  **Best Practice**: Keep web environment files in your repository and ensure all values are non-sensitive. If you need to reference sensitive data from the frontend, create a secure API endpoint that returns the necessary information after proper authentication.
</Tip>

# Setting up GitHub Actions CI/CD

### Creating IAM user in AWS

To set up CI/CD with GitHub Actions securely, we need to create a dedicated IAM user in AWS with specific permissions.

This separate user will be used exclusively for CI/CD operations, following the principle of least privilege and keeping deployment credentials isolated from other system users.

<Steps>
  <Step title="Create IAM Policy">
    1. Go to [AWS IAM Policies](https://console.aws.amazon.com/iam/home#/policies)
    2. Click **Create policy**
    3. Select **JSON** tab and add the policy:

    ```json  theme={null}
    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Sid": "ECR",
                "Effect": "Allow",
                "Action": [
                "ecr:BatchGetImage",
                "ecr:CompleteLayerUpload",
                "ecr:GetAuthorizationToken",
                "ecr:UploadLayerPart",
                "ecr:InitiateLayerUpload",
                "ecr:BatchCheckLayerAvailability",
                "ecr:PutImage"
              ],
               "Resource": "*"
            },
            {
                "Sid": "EKS",
                "Effect": "Allow",
                "Action": "eks:DescribeCluster",
                "Resource": "*"
            }
        ]
    }
    ```

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-config.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=5aafd64f1af3b096629a2fcd71d8f190" alt="Policy Configuration" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/policy-config.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-config.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=557d13b4a1bdebfff06d96435c652934 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-config.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=93a0498f78cc518d675b3e114dba4650 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-config.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=8efa920f3fdbb96723292fb495af1c00 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-config.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=efef45ae62efcd217a16ab7f0efd5391 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-config.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7e2c9b158e64c6c0d174a7e96f4945dd 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-config.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e0c6e0a3e58d978b0bbb553f7ce28f5b 2500w" />
    </Frame>

    4. (Optional) Add tags
    5. Give the policy a name (e.g. `GitHubActionsDeployPolicy`) and create it

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-review-create.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c538c135b4ff0c097298fcb8b1991e70" alt="Policy review create" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/policy-review-create.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-review-create.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6fce3939bdd1cb7e62adca7e93e977dd 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-review-create.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c6c4043923662501edd37f6b44470fd0 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-review-create.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f792ed7529e6232ec2062f57d4915d75 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-review-create.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=97e857b47ee02304ad39d384ed33f2d5 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-review-create.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4b521d350940fdf9673fcd44675eb075 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/policy-review-create.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=75d33e76a2a52bc095766712a84acec9 2500w" />
    </Frame>
  </Step>

  <Step title="Create IAM User">
    1. Navigate to **Users** in IAM console
    2. Click **Create user**
    3. Give the user a name (e.g. `github-actions`)

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-creating.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d3a22ad5afc28a85f4b446f4271f195d" alt="User creating" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/user-creating.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-creating.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=69b296b0326d94d912bc79277eba91ea 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-creating.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=51dc24551ebed3b77ca88069e79cc92e 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-creating.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0609c24636b234c5448a99c93ecd0801 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-creating.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=ac06f64954847b62a3d8f1ef2f1c9093 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-creating.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9e6a927fc7621159f5808025e2a43f3f 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-creating.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=e917308c2e357ea0c01fa3d500931733 2500w" />
    </Frame>

    4. Attach the policy you created by selecting:

    * **Attach existing policies directly**
    * Choose the CI/CD policy created in previous step

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-policy.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=ce51aaf2d95b180dfea80951d8759a61" alt="User policy" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/user-policy.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-policy.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a044076d7774a96f9e519e755b6f8551 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-policy.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0480a85af31207d88ac1e72d7612ab47 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-policy.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4476c0e4a337c01ccb0b23954c564f8d 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-policy.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=895886d0930963a6092043106e30fa06 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-policy.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b3719148c9a418cb13551bdbc44d47a0 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-policy.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f76ec40f205232b959c355fd7a8a0391 2500w" />
    </Frame>

    4. (Optional) Add user tags
    5. Review and create user
  </Step>

  <Step title="Generate Access Keys">
    1. Find your new user in the users list and open user's page
    2. Click **Create access key**

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-create-access-key.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d6f0ef45b8f5bff7933c8775c4f2b121" alt="User create access key" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/user-create-access-key.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-create-access-key.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=22fa57babdf33278ba0f130663508eb9 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-create-access-key.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f14d5e408c47b9ad3fd542e93312e26e 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-create-access-key.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4ec8ee11b742f5cd065b3eaaff65d95c 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-create-access-key.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c2ad43bbdbb1bd1ebc294eb3ac5d85ca 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-create-access-key.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=24d22f0dfc814f2e2f630ab946f54585 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-create-access-key.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0844781fc5abab471a4cc179026e9af0 2500w" />
    </Frame>

    3. Select use case: **Third-party service**

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-access-key-use-case.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=21b3e38eb123d2ca1c3c3a3e90729737" alt="User access key use cases" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/user-access-key-use-case.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-access-key-use-case.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=78719f2899605a266cac831197f571f8 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-access-key-use-case.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=48920588f99cd55c263509fe8cd216aa 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-access-key-use-case.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=5fd4511d0266b9e7574a22d9f57428e0 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-access-key-use-case.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9ed644215e662f9d2fdfd56e5fcefcbd 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-access-key-use-case.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=dc216013aa4c6888e12b6b6a35c1ee53 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-access-key-use-case.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2de8f927c17499286b4ff262754e0b08 2500w" />
    </Frame>

    4. Save the Access Key ID and Secret Access Key securely

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-credentials.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=57a15e1034a28d573426434b4032507d" alt="User credentials" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/user-credentials.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-credentials.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0b6ad99abb4d4af5bd13904b6f230b75 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-credentials.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7179c2bd1d5189bd76c17e34519cc333 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-credentials.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a5230cba306623c826df42330451b952 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-credentials.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d66e7d0a9e54d19dea8d988287b836be 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-credentials.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=42727aeaa6b7a49fb61a5b7022f5ca34 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-credentials.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=23155461e21367f80e7b5c442365f789 2500w" />
    </Frame>

    <Warning>
      The Secret Access Key will only be shown once - make sure to save it immediately!
    </Warning>
  </Step>

  <Step title="Configure EKS Access">
    1. Copy your user's ARN from the IAM dashboard

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-arn.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=92412e68ac0bbc613e8a91ed9be81a52" alt="User ARN" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/user-arn.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-arn.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1d0ec2524dc537d7b35ee0faa844f8e1 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-arn.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1394d49ab5820127d28db7952dc73bf6 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-arn.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f6729ed35af19d54cb0ec303fcec334e 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-arn.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=27fef8314734f29abd51c4b874d17524 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-arn.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=77a67f31c376092eed1b57990606fe3d 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/user-arn.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6efcc118ea00a27f6eeaf3db252e48bd 2500w" />
    </Frame>

    2. Run the following command to grant Kubernetes access:

    ```bash  theme={null}
    eksctl create iamidentitymapping \
    --cluster my-ship-app \
    --group system:masters \
    --username github-actions \
    --arn YOUR_USER_ARN
    ```

    Replace `YOUR_USER_ARN` with the actual ARN copied earlier.
  </Step>
</Steps>

<Note>
  These permissions enable CI/CD workflows while following security best practices:

  * Minimal required permissions for ECR operations
  * Limited EKS access for cluster management
  * Dedicated CI/CD user separate from other IAM users
</Note>

### Configuring GitHub Actions secrets and variables

<Note>
  Before starting, make sure you have created a GitHub repository for your project.
</Note>

GitHub Secrets and variables allow you to manage reusable configuration data.

Secrets are encrypted and are used for sensitive data. [Learn more about encrypted secrets](https://docs.github.com/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets).

Variables are shown as plain text and are used for non-sensitive data. [Learn more about variables](https://docs.github.com/actions/learn-github-actions/variables).

<Tip>
  The deployment will be triggered on each commit:

  * Commits to **main** branch → deploy to **staging** environment
  * Commits to **production** branch → deploy to **production** environment
</Tip>

[Configure](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) the following secrets and variables in your GitHub repository:

| Name                      | Type     | Description                                                                                                                 |
| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| AWS\_SECRET\_ACCESS\_KEY  | secret   | The secret access key from the AWS IAM user created for CI/CD. This allows GitHub Actions to authenticate with AWS services |
| AWS\_ACCESS\_KEY\_ID      | variable | The access key ID from the AWS IAM user. Used in conjunction with the secret key for AWS authentication                     |
| AWS\_REGION               | variable | The AWS region where your EKS cluster and ECR registry are located (e.g. `us-east-1`)                                       |
| CLUSTER\_NODE\_GROUP      | variable | The name of the EKS node group where your application pods will be scheduled (e.g. `pool-app`)                              |
| CLUSTER\_NAME\_PRODUCTION | variable | The name of your production EKS cluster. Required when deploying to the production environment                              |
| CLUSTER\_NAME\_STAGING    | variable | The name of your staging EKS cluster. Required when deploying to the staging environment                                    |

<Warning>
  Never commit sensitive credentials directly to your repository. <br />
  Always use GitHub Secrets for sensitive information like AWS keys.
</Warning>

<Note>
  Variables (unlike secrets) are visible in logs and can be used for non-sensitive configuration values that may need to be referenced or modified.
</Note>

<Frame>
  <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-secrets.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d0f98fb2efd13820b5292936b4ae6666" alt="GitHub Secrets" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/gh-secrets.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-secrets.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7aec622b08cce9486c223d26f42f48f5 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-secrets.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c6ff12f9118ea358e74f760deab1dd6d 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-secrets.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6aa3f99c8ac65570c38c0d8e1aaa862a 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-secrets.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=bd81d8ac53bdacdbd0602b1d757c55ea 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-secrets.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c35522296f55b06f157ec82a4877ed80 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-secrets.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d0e4599d2f2a27b963f1ebfdad612394 2500w" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-variables.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=432e47679d6f6bdd5e1148549ecb5494" alt="GitHub Variables" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/gh-variables.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-variables.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=26e5e75cf287895a9bbddb6c1d35899f 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-variables.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=082f28946ed2f652632e4729bb066137 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-variables.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=734575499a3a38d2c13a06d2eb49a536 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-variables.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=693190521767a8f4ded3adbd6574f0f0 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-variables.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6d9958fcb79359a705d61b5e0926c3e7 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/gh-variables.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b973025deb9d693fd34ec6532085a575 2500w" />
</Frame>

Now commit all changes to GitHub that will trigger deployment, or you can [run a workflow manually](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow)

<Frame>
  <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-start.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2ea0954426e339029037129e9f333c87" alt="CI start" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/ci-start.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-start.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2f29b1383bfab25f44d33f8e86dadf8d 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-start.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7aea9e682b18982ccbcc512488b2ad9d 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-start.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c01b9604f95399dbdd621646a0e0bd2a 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-start.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=792ea95434bcc37bbe028f5ae11ede82 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-start.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=efba40d6636f7d1eb88b0fdc614b7cb9 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-start.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1cf3cf45451e3b9027352112c68cdd7a 2500w" />
</Frame>

Done! Application deployed and can be accessed by the provided domain.

<Frame>
  <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-finish.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d28722ec3a6257d73cbd9b43cecd530d" alt="CI finish" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/aws/ci-finish.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-finish.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=25ab0d91e757d31a892f275438e2fc57 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-finish.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=fbf13f04a00f85d8be5fe6ed5aa3252e 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-finish.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=51e291dc5277a0a84be61bbbb30134a3 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-finish.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=8b36a96ba93458ad8976fada6a4b6ba6 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-finish.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7145ecbc2683eed509f18eb28b94a1d8 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/ci-finish.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7db72e5ca40d480811e47b086a798024 2500w" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployment-finish.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f4c2b9b8afd06f9bc85efda377c05abd" alt="Deployment finish" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/aws/deployment-finish.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployment-finish.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=fe9c014970fa76a5ef38867f53bc25c2 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployment-finish.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=8f95c0e544e3de85adfe63afe2248543 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployment-finish.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=81abadf9615320b58e1d0eeeeec3b1a1 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployment-finish.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=685fe67f132f555e2d6b037cf089a53e 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployment-finish.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=626a92a364dd0c137fc9f2892dc27f69 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployment-finish.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=efe8ed4077e8073ac417637b99493338 2500w" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployed-pods.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d74e585dc0f3be76c6d008a3179872d3" alt="Deployed pods" data-og-width="2244" width="2244" data-og-height="1252" height="1252" data-path="images/aws/deployed-pods.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployed-pods.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2a8214189e924e4770acd82427cadec5 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployed-pods.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1f7640f57b7f5b1e89c74d8138ff1ed8 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployed-pods.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2ce10b4e1f33bf6e3889a9a1092f9d36 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployed-pods.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6463f2b57aeade6e705ab92ec4c5d0c6 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployed-pods.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=73abe44e62e7e3fc1c605286fa5e2b6c 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/aws/deployed-pods.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=099a758f30f4a709d6b81f697d9a919e 2500w" />
</Frame>

<Tip>
  If something went wrong you can check the workflows logs on GitHub and use [**kubectl logs**](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#interacting-with-running-pods), [**kubectl describe**](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#viewing-finding-resources) commands.
</Tip>

## Setting up Upstash Redis database (recommended)

# Upstash Redis Integration

[Upstash Redis](https://upstash.com/) is a **highly available, infinitely scalable** Redis-compatible database that provides enterprise-grade features without the operational complexity.

## How Ship Uses Redis

Ship leverages Redis for several critical functionalities:

| Use Case                    | Description                                       | Implementation                                                      |
| --------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
| **Real-time Communication** | Pub/Sub mechanism for WebSocket functionality     | [Socket.io Redis Adapter](https://socket.io/docs/v4/redis-adapter/) |
| **Rate Limiting**           | API request throttling and abuse prevention       | Redis counters with TTL                                             |
| **Caching**                 | Application data caching for improved performance | Key-value storage with expiration                                   |

<Info>
  **Redis as a Message Broker**: When scaling to multiple server instances, Redis acts as a message broker between Socket.io servers, ensuring real-time messages reach all connected clients regardless of which server they're connected to.
</Info>

## Setting Up Upstash Redis

### Create Your Database

<Steps>
  <Step title="Access Upstash Console">
    Log in to your [Upstash account](https://console.upstash.com/) and navigate to the Redis section.
  </Step>

  <Step title="Create New Database">
    Click **Create Database** in the upper right corner to open the configuration dialog.

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c7797ba6b2a8538f611365d30d553c7e" alt="Create Upstash Redis Database" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/upstash-redis/create-global.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5b7a389c8d214bc071a66198668abe3d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7d1c21021d77ef784502bd42e0d34527 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=75369756145d7d2d776587624eff70ce 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ab63aa595dcea30cd127a57ec648f030 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4eb03d1621b7945054d2fc95e99e200c 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1f5a79ac57a43abdd12f27bf6f08033b 2500w" />
    </Frame>
  </Step>

  <Step title="Configure Database Settings">
    **Database Name:** Choose a descriptive name for your database (e.g., `my-ship-app-production`)

    **Primary Region:** Select the region closest to your main application deployment for optimal write performance.

    **Read Regions:** Choose additional regions where you expect high read traffic for better global performance.
  </Step>

  <Step title="Select Plan & Deploy">
    Choose your pricing plan based on expected usage and click **Create** to deploy your database.
  </Step>
</Steps>

<Tip>
  {provider_0 === 'aws' && (
      <p>
        <strong>Region Selection:</strong> For Kubernetes deployments on AWS, choose the same AWS region as your EKS cluster to minimize latency and data transfer costs.
      </p>
    )}

  {provider_0 === 'do' && (
      <p>
        <strong>Region Selection:</strong> For Kubernetes deployments on Digital Ocean, choose the same region as your cluster to minimize latency and data transfer costs.
      </p>
    )}
</Tip>

Once your database is created, you'll need the connection string for your application:

<Steps>
  <Step title="Navigate to Connection Info">
    Go to your database dashboard and find the **Connect to your database** section.

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=9705f2cee3b707820948d3eec2f08734" alt="Upstash Redis Connection Details" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/upstash-redis/database.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=82c1b77e1af7b30332799d149b745146 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=3ff403da9211a59291dbf8637932b5a8 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=fff28964c02ef9da805ee49a6d64f34c 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=3c0e99bd0e2a14df3ba14e702ca294ef 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=796fc214062d077d94d429d026a55a6d 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=9a9ffcd82f4eae9a5bfbc2b9151ce375 2500w" />
    </Frame>
  </Step>

  <Step title="Copy Connection String">
    1. Select the **Node** tab for the appropriate connection string format
    2. Click **Reveal** to show the hidden password
    3. Copy the complete Redis URI (format: `rediss://username:password@host:port`)
  </Step>

  <Step title="Add to Environment Variables through k8sec">
    Using `k8sec`, add the Redis connection string to your environment configuration:

    <CodeGroup>
      ```bash production theme={null}
      k8sec set api-production-secret -n production REDIS_URI=$REDIS_URI
      ```

      ```bash staging theme={null}
      k8sec set api-staging-secret -n staging REDIS_URI=$REDIS_URI
      ```
    </CodeGroup>

    <Note>
      After updating environment variables, restart your API pod using:

      ```bash  theme={null}
      kubectl delete pod <pod-name> -n <namespace>
      ```

      This will trigger Kubernetes to create a new pod with the updated environment variables.
    </Note>
  </Step>
</Steps>

### Verify Connection with Redis Insight

Redis Insight is a powerful GUI tool for managing and debugging Redis databases.

<Steps>
  <Step title="Install Redis Insight">
    Download and install [Redis Insight](https://redis.io/insight/) on your local machine.
  </Step>

  <Step title="Add Database Connection">
    1. Open Redis Insight
    2. Click **Add Database**
    3. Paste your Upstash Redis connection string in the **Connection URL** field
    4. Click **Add Database**

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=dc5072c3077144b8c0ebd997c1595074" alt="Redis Insight Connection Setup" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/upstash-redis/redis-insight.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7d7b1d2063b3d8e22dd1b286771a9b25 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=083f32d2ed3b0c958d75210820df995b 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=fc6d38ddd7396e9588d5e95f5392df56 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e3b4ae2d98c46bf9cb9358401ec3e611 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=60b52d55861635b2c16bf10098777df5 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ee88e812ad858956387d744c92a811e2 2500w" />
    </Frame>
  </Step>

  <Step title="Explore Your Database">
    Once connected, you can use Upstash Redis Console to:

    * Browse keys and data structures
    * Execute Redis commands directly
    * Monitor real-time performance metrics
    * Debug application data storage

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a5bc78e23381ab469980479d247270b8" alt="Upstash Redis Metrics Dashboard" data-og-width="1271" width="1271" data-og-height="279" height="279" data-path="images/upstash-redis/charts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=546f6728b651e70cb51169f9c42f3be4 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6694a5c3f6e6d26b9dd6193d1fc76dc2 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=677dc96a96a9621074bc7857d9ffdfe3 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bd722d61192a9e2be9b51794f748ea3c 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4fed9af7f4496af0179e3fedf6761435 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cad48a52efeed8e0513abe1e64cc4719 2500w" />
    </Frame>

    <Info>
      **Real-time Monitoring**: Upstash Redis updates database metrics automatically every 10 seconds, giving you near real-time visibility into your Redis performance and usage.
    </Info>
  </Step>
</Steps>


# Digital Ocean
Source: https://ship.paralect.com/docs/deployment/kubernetes/digital-ocean



export const provider_1 = "do"

export const provider_0 = "do"

It's a step-by-step Ship deployment guide. We will use Digital Ocean Managed [Kubernetes](https://www.digitalocean.com/products/kubernetes), [Container Registry](https://www.digitalocean.com/products/container-registry), [Mongo Atlas](https://www.mongodb.com/), [GitHub Actions](https://github.com/features/actions) for automated deployment, and [CloudFlare](https://www.cloudflare.com/) for DNS and SSL configuration.

You need to create [GitHub](https://github.com/), [CloudFlare](https://www.cloudflare.com/), [Digital Ocean](https://www.digitalocean.com/) and [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) accounts and install the next tools on your machine before starting:

* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) - CLI tool for accessing Kubernetes cluster;
* [kubectx](https://github.com/ahmetb/kubectx) - CLI tool for easier switching between Kubernetes contexts;
* [helm](https://helm.sh/docs/intro/install) - CLI tool for managing Kubernetes deployments;
* [k8sec](https://github.com/dtan4/k8sec) - CLI tool for managing Kubernetes Secrets easily;

<Accordion title="How to install k8sec on Linux?">
  Download k8sec tar.gz, then do:

  ```
  chmod +x k8sec
  ```

  ```
  sudo cp k8sec /usr/local/bin/
  ```

  ```
  k8sec --help
  ```
</Accordion>

Try the next commands to ensure that everything is installed correctly:

```
kubectl

kubectx

helm

k8sec
```

Also, you need [git](https://git-scm.com/) and [Node.js](https://nodejs.org/en/) if you already haven't.

## Setup project

First, initialize your project. Type `npx create-ship-app@latest` in the terminal then choose **Digital Ocean Managed Kubernetes** deployment type.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b8dd3d65c41aac6cc96db19ef72637ac" alt="Init project" data-og-width="739" width="739" data-og-height="748" height="748" data-path="images/init-project.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1d4182a699988dcdc7a062792ed64a55 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f11b56dd940643183fb357af5deb5055 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=800d987b87f99226ed191324417de1e1 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a0f335955aa56a7c66000bff6c225ad1 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6de7c05d7d4ed5cba27cb7d9d157f797 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=220330c4c1229776bc2ccd165003c646 2500w" />

You will have next project structure.

```shell  theme={null}
/my-ship-app
  /.github
  /apps
    /api
    /web
  /deploy
  ...
```

## Container registry

You need to create [Container Registry](https://www.digitalocean.com/products/container-registry) for storing Docker images. The deployment script will upload images to Container Registry during the build step, and Kubernetes will automatically pull these images from Container Registry to run a new version of service during the deployment step.

Name container registry as the name of organization, which usually is equals to the name of the project: `my-ship-app`.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-creation.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=13af0e4c08793a40c54578701dbecebd" alt="Container Registry creation" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/container-registry-creation.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-creation.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=295f6108eb5d9e9590e3213ad51ae290 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-creation.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=19b9c083d4db95bc9163fd133a91ca77 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-creation.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=eb89dfc864f592260ccbfe99d8c5667a 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-creation.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=5b3f457add3847cd1827b8af6008c906 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-creation.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=d995e43678aea538870515bad6ef32c9 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-creation.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9a176959538b866d94901e65fe641873 2500w" />

After some time, you will get registry endpoint.

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-created.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=fa418298b77bfbbb2cbe59315c92f55d" alt="Container Registry creation" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/container-registry-created.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-created.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9a38819988a25ace5860d1341f7e8a76 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-created.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=301d1a57f238a6d1309e71b95c24acbd 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-created.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=38f5af3cb19a2130c7de038d208baf97 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-created.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1f8ed7c17931b6cbfddf3e7ce186414d 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-created.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2c98fd1e32fb639663ce23369603e604 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/container-registry-created.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=0bd33035b908ef08aecb969b7cc9e5a3 2500w" />

`registry.digitalocean.com/my-ship-app` is registry endpoint, where `my-ship-app` is registry name.

Docker images for each service are stored in separate repository.
In Digital Ocean repositories are created automatically when something is uploaded by specific paths.
During deployment process script will automatically create paths to repositories in next format:

* [**API**](/api-reference/overview) - registry.digitalocean.com/my-ship-app/api;
* [**Scheduler**](/scheduler) - registry.digitalocean.com/my-ship-app/scheduler;
* [**Migrator**](/migrator) - registry.digitalocean.com/my-ship-app/migrator;
* [**Web**](/web/overview) - registry.digitalocean.com/my-ship-app/web;

<Tip>
  Images for all environments will be uploaded to the same repository for each
  service.
</Tip>

## Kubernetes cluster

Now let's create [Managed Kubernetes](https://www.digitalocean.com/products/kubernetes) cluster.

<Steps>
  <Step title="Select a region">
    Navigate to the cluster creation page [here](https://cloud.digitalocean.com/kubernetes/clusters/new)<br />

    <Tip>
      We recommend you to create a cluster in the region where your end-users are located, it will reduce response time to incoming requests to all services.
    </Tip>

    <Tip>
      Also, if your cluster will be located in one region with a Container Registry deployment process will be faster. You can find more information about regions [here](https://docs.digitalocean.com/products/platform/availability-matrix/).
    </Tip>

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-region.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b399232783f9d66b1390fc2f2d3d74e1" alt="Cluster Region" data-og-width="1092" width="1092" data-og-height="854" height="854" data-path="images/cluster-region.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-region.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=bf1e46eea1365d2469e65b5c5cd9ecd2 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-region.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=de540f5dfbb0d14e90684aa61a9462a0 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-region.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=438fa4853ab82ef1f30c31608194d910 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-region.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a1f603a5d6e973b12405d3c1ede287d3 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-region.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=aac70475a927a2bad90896a6a9aa3257 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-region.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=775d52fbb23f3727ef16fbc9042f1b79 2500w" />
    </Frame>
  </Step>

  <Step title="Set Node pool name">
    Set Node pool name (e.g. `pool-app`) and configure Nodes.
    Digital Ocean recommends creating at least 2 nodes for the production environment. These settings will have an impact on the price of the cluster.

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-capacity.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=aed2e1f69fd9e2b0ebd0166a7d7979ad" alt="Cluster Capacity" data-og-width="1103" width="1103" data-og-height="819" height="819" data-path="images/cluster-capacity.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-capacity.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=918cad3c30313ef662e99df2f67f63d0 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-capacity.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b222621aaf745fa3c82885fad6e897ce 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-capacity.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=a82e08c7906ea4ac80b5786bd66846d1 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-capacity.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=7bde219cf3c852b492fb49be2caee9e4 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-capacity.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=557a78ea2accf60847134f94dba3ac45 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-capacity.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f9207e934f5b10accd19a72725c3c4c7 2500w" />
    </Frame>
  </Step>

  <Step title="Set cluster name">
    Set cluster name (e.g. `my-ship-app`). A common practice is to use the project name for it.

    <Frame>
      <img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-name.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=48c3bde8ed49a5454a13b27ad633e0c2" alt="Cluster Name" data-og-width="1086" width="1086" data-og-height="763" height="763" data-path="images/cluster-name.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-name.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=50431156898f58e2c56c0b677712eefe 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-name.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=072124dc681d94a4c1f97788d930fef3 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-name.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=1337206757304bc79b4c6ee2977e0d59 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-name.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3ee4e82bfe5ca47a44b88e8fb389c5cd 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-name.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=035601996f1b35ef0e2b4b5e2ee16a2a 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cluster-name.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=3e16caf7bd89553623980402b13d154d 2500w" />
    </Frame>
  </Step>

  <Step title="Review and Create">
    Click on `Create Kubernetes Cluster` button to create a cluster and wait for cluster to be ready.
  </Step>

  <Step title="Integrate with created Container Registry">
    After cluster is created, go to the Container Registry's settings and find `DigitalOcean Kubernetes integration` section.

    <Frame>
      <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-settings.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ad9514438f83f225bd57ab1a12ac0281" alt="Registry Settings" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/do/registry-settings.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-settings.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7e29f15de5f837a48eaeb029c3278d88 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-settings.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=81974a55fe73b8986e4b34bd12508b26 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-settings.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9d629df41e9faefb4bf514be2367c37a 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-settings.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=978954187380ee7cdbabb30b79f5e369 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-settings.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=41e6bfe2bd3581b2c38bc69216637421 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-settings.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9157e3dfaeb7d78bdb594048be6b696f 2500w" />
    </Frame>

    You need to select your newly created `my-ship-app` cluster.

    <Frame>
      <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-check-cluster.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=184db4c77fe2d3a40cdbf06fc3f1f3dc" alt="Registry Check Cluster" data-og-width="599" width="599" data-og-height="298" height="298" data-path="images/do/registry-check-cluster.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-check-cluster.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0bdff5cb6f45ebe8fb02076de3a060b1 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-check-cluster.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3bec79285f09066ed93f4dd1a49aeb41 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-check-cluster.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=356a6dd76e1c832445b3fc9d6a2d1f32 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-check-cluster.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c09aa512c8269e5ef192371fe605347b 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-check-cluster.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=313bc68f21b27cdad17642d98deeefe8 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/registry-check-cluster.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dddd49d5f2768efafe9c8ff7d7148d9e 2500w" />
    </Frame>
  </Step>
</Steps>

## Personal access token

To upload docker images in Container Registry and pull them after from cluster we need Digital Ocean [Personal Access Token](https://cloud.digitalocean.com/account/api/tokens).
When you created cluster - one with **Read Only** scope was automatically created.

But we need to [generate](https://cloud.digitalocean.com/account/api/tokens/new) a new one with:

* Name (e.g. `my-ship-app-admin-deploy`)
* **Full Access** scope
* No expiration

<Tip>
  You cannot change scope of already generated token.
</Tip>

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-token.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=7784d0982ccdfa63d2804a42fbefe508" alt="Digital Ocean Token" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/do-token.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-token.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bbe632bcca1f48f9d46a191eb5c8cec7 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-token.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=957a7cc3689cc2ad6bfc9944cd257891 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-token.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3b710092464ae192b90650748c1d581d 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-token.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1464f80fc4d40ba261cad0024d071a74 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-token.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fe0156ffbbbf84ad73d15240e6c7a097 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do-token.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d10a31264537008f9c63e42a325ba8be 2500w" />

We will need this token soon, so don't close this page yet.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/full-access-token.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c4da1154ca9149466b8abf1ed8e5cbdc" alt="Digital Ocean Token" data-og-width="1214" width="1214" data-og-height="679" height="679" data-path="images/do/full-access-token.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/full-access-token.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=708f9ed4dd14786da2bcb73e0a0b93db 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/full-access-token.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d2c9e1824aeb0142f31918e9fd75101f 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/full-access-token.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=13b38c5ac40125f37d19d33af18baac3 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/full-access-token.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=26e0710f7d84b106ec0cdebb698714f8 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/full-access-token.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=cfce5f7b5ace06409886f95bd583547f 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/full-access-token.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e893ecc49f91adc8104b9bc76dd4dfa3 2500w" />

<Warning>
  Be very careful with Personal Access Token, if someone steals it he will get access
  to all resources from your Digital Ocean account.
</Warning>

## Accessing cluster from a local machine

<Steps>
  <Step title="Download cluster's kubeconfig">
    Download cluster's kubeconfig, this file includes information for accessing cluster through `kubectl`.

    <Frame>
      <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/kubeconfig-download.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=37bde52b3ccb34f20567040baa217ee0" alt="Kubeconfig Download" data-og-width="1274" width="1274" data-og-height="637" height="637" data-path="images/kubeconfig-download.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/kubeconfig-download.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a7f1c7262dfeab128539232773e6ed7c 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/kubeconfig-download.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=19af7c66e59d0d19d8ca14567b1c4c5d 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/kubeconfig-download.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=89ea267097c6e13b335c47bf7b824085 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/kubeconfig-download.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=753953c539e6527432197383b1e6524d 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/kubeconfig-download.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=68764bb56a60d5e8b57d39fa71ec0d9e 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/kubeconfig-download.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0e76fb406f3cb93374ff820ddd2aaf3c 2500w" />
    </Frame>

    <Accordion title="Expected structure of downloaded kubeconfig">
      ```yaml my-ship-app-kubeconfig.yaml theme={null}
      apiVersion: v1
      clusters:
      - cluster:
          certificate-authority-data: ...
          server: https://...
        name: do-nyc3-my-ship-app
      contexts:
      - context:
          cluster: do-nyc3-my-ship-app
          user: do-nyc3-my-ship-app-admin
        name: do-nyc3-my-ship-app
      current-context: do-nyc3-my-ship-app
      kind: Config
      preferences: {}
      users:
      - name: do-nyc3-my-ship-app-admin
        user:
          token: dop_v1_...
      ```
    </Accordion>

    And replace initial **Read only** token with new **Full access** token from [Personal access token](#personal-access-token) section.

    ```yaml my-ship-app-kubeconfig.yaml {18-19} theme={null}
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: ...
        server: https://...
      name: do-nyc3-my-ship-app
    contexts:
    - context:
        cluster: do-nyc3-my-ship-app
        user: do-nyc3-my-ship-app-admin
      name: do-nyc3-my-ship-app
    current-context: do-nyc3-my-ship-app
    kind: Config
    preferences: {}
    users:
    - name: do-nyc3-my-ship-app-admin
      user:
        # replace this token for full access token
        token: dop_v1_...
    ```
  </Step>

  <Step title="Add cluster, context and user to kubeconfig">
    <Tip>
      [Kubeconfig](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/) files contain information about several clusters, you have your own on the local machine, it should have been created after `kubectl` installation.
    </Tip>

    You need to add information about the new cluster to your kubeconfig.
    Find `.kube/config` file on your machine, and add `cluster`, `context` and `user` values from `my-ship-app-kubeconfig.yaml`.

    ```yaml ~/.kube/config {7-11, 17-21, 29-33} theme={null}
    apiVersion: v1
    clusters:
    - cluster:
        certificate-authority-data: ...
        server: https://...
      name: some-cluster
    # your new cluster from my-ship-app-kubeconfig.yaml goes here
    - cluster:
        certificate-authority-data: ...
        server: https://...
      name: do-nyc3-my-ship-app
    contexts:
    - context:
        cluster: some-cluster
        user: some-user
      name: some-cluster
    # your new context from my-ship-app-kubeconfig.yaml goes here
    - context:
        cluster: do-nyc3-my-ship-app
        user: do-nyc3-my-ship-app-admin
      name: do-nyc3-my-ship-app
    current-context: some-cluster
    kind: Config
    preferences: {}
    users:
    - name: some-user
      user:
        token: dop_v1_...
    # your new user from my-ship-app-kubeconfig.yaml goes here
    - name: do-nyc3-my-ship-app-admin
      user:
        token: dop_v1_...
    ```
  </Step>

  <Step title="Switch to cluster context">
    Execute kubectx in your terminal and select your cluster from the list.

    ```shell  theme={null}
    kubectx
    ```

    You will see the list of available clusters.

    ```shell  theme={null}
    some-cluster
    do-nyc3-my-ship-app
    ```

    Select your cluster from the list:

    ```shell  theme={null}
    kubectx do-nyc3-my-ship-app
    ```
  </Step>

  <Step title="Verify cluster access">
    Check the installed pods by running:

    ```shell  theme={null}
    kubectl get pods -A
    ```

    You should see a list of system pods in your cluster:

    ```shell  theme={null}
    NAMESPACE     NAME                            READY   STATUS    RESTARTS   AGE
    kube-system   cilium-tb8td                    1/1     Running   0          18m
    kube-system   cilium-x5w8n                    1/1     Running   0          19m
    kube-system   coredns-5679ffb5c8-b7dzj        1/1     Running   0          17m
    kube-system   coredns-5679ffb5c8-d465r        1/1     Running   0          17m
    kube-system   cpc-bridge-proxy-ebpf-2gzfr     1/1     Running   0          17m
    kube-system   cpc-bridge-proxy-ebpf-jknzh     1/1     Running   0          17m
    kube-system   csi-do-node-jcqd2               2/2     Running   0          17m
    kube-system   csi-do-node-rpx6q               2/2     Running   0          17m
    kube-system   do-node-agent-ldhxq             1/1     Running   0          17m
    kube-system   do-node-agent-pdksz             1/1     Running   0          17m
    kube-system   hubble-relay-66f54dcd57-l7xjb   1/1     Running   0          21m
    kube-system   hubble-ui-785bdbc45b-6xd57      2/2     Running   0          18m
    kube-system   konnectivity-agent-h79mt        1/1     Running   0          17m
    kube-system   konnectivity-agent-hvv67        1/1     Running   0          17m
    ```
  </Step>
</Steps>

## Ingress NGINX Controller

[ingress-nginx](https://github.com/kubernetes/ingress-nginx) is an Ingress controller for Kubernetes using [NGINX](https://nginx.org) as a reverse proxy and load balancer.

<Tip>
  Learn more about ingress-nginx functionality in the **[official documentation](https://docs.nginx.com/nginx-ingress-controller/intro/how-nginx-ingress-controller-works/)**.
</Tip>

<Steps>
  <Step title="Navigate to dependencies directory">
    Change to the `deploy/dependencies` directory in your terminal.
  </Step>

  <Step title="Configure Helm Values (Optional)">
    This step is required **only if** you specified a custom node pool name in your Digital Ocean Kubernetes cluster.

    If you did, update the `doks.digitalocean.com/node-pool` value in `values.yaml.gotmpl`:

    ```yaml deploy/dependencies/ingress-nginx/values.yaml.gotmpl {5} theme={null}
    controller:
      publishService:
        enabled: true
      nodeSelector:
        doks.digitalocean.com/node-pool: pool-app

    rbac:
      create: true

    defaultBackend:
      enabled: false
    ```
  </Step>

  <Step title="Install dependencies">
    Install helm dependencies using helmfile:

    ```bash  theme={null}
    helmfile deps
    ```
  </Step>

  <Step title="Review and apply changes">
    Preview the changes first:

    ```bash  theme={null}
    helmfile diff
    ```

    If the preview looks correct, apply the configuration:

    ```bash  theme={null}
    helmfile apply
    ```
  </Step>
</Steps>

## DNS and SSL

<Steps>
  <Step title="Get Load Balancer Address">
    After deploying ingress-nginx, retrieve the Load Balancer's external ip:

    ```bash  theme={null}
    kubectl get svc ingress-nginx-controller -n ingress-nginx
    ```

    Copy the value from the `EXTERNAL-IP` column.

    ```shell  theme={null}
    NAME                       TYPE           CLUSTER-IP       EXTERNAL-IP      PORT(S)                      AGE
    ingress-nginx-controller   LoadBalancer   10.245.201.160   138.68.124.241   80:30186/TCP,443:32656/TCP   28m
    ```

    <Tip>
      It take some time while **ingress-nginx** will configure everything and
      provide `EXTERNAL-IP`.
    </Tip>
  </Step>

  <Step title="Domain Naming Convention">
    You can follow this recommended naming pattern for different environments:

    | Environment | API Domain           | Web Domain           |
    | ----------- | -------------------- | -------------------- |
    | Production  | api.ship.com         | app.ship.com         |
    | Staging     | api.staging.ship.com | app.staging.ship.com |
  </Step>

  <Step title="Configure DNS in Cloudflare">
    1. First, ensure you have a domain in Cloudflare. You can either:

    * [Register a new domain](https://developers.cloudflare.com/registrar/get-started/register-domain/)
    * [Transfer an existing domain](https://developers.cloudflare.com/registrar/get-started/transfer-domain-to-cloudflare/)

    2. In the Cloudflare DNS tab, create 2 `A` records:

    * One for Web interface
    * One for API endpoint

    Both should point to your Load Balancer's external hostname.

    Enable the **Proxied** option to:

    * Route traffic through Cloudflare
    * Generate SSL certificates automatically

    <Frame>
      <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-api.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=fd34db7ae916dc5f087d0fbf09c68ff1" alt="CloudFlare API DNS Configuration" data-og-width="1242" width="1242" data-og-height="411" height="411" data-path="images/do/cloudflare-api.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-api.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b39f9ca86db30de3848627421f862637 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-api.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6e4b81218f38120e92a3e16869dce144 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-api.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=64cbba04ba814bf1a541e0e0bd5009f6 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-api.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4eb0a6126bfd738392b15a5bd8306ed3 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-api.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=21ea7fb0dd8f759949123f130f9a5c4e 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-api.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a214a8e7ddc4b7d8efd069694bb78685 2500w" />
    </Frame>

    <br />

    <Frame>
      <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-web.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=aa381fe09926d96df84ea6ea1118e6fb" alt="CloudFlare Web DNS Configuration" data-og-width="1226" width="1226" data-og-height="402" height="402" data-path="images/do/cloudflare-web.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-web.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f2ab086d40989091dad4004f9db4e2a1 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-web.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=157a77eaae7edfe236abf1bd14e59403 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-web.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0650273983e0b260dc50695e970d6512 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-web.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9455eec63291ab2837bad7a2307f83b9 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-web.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=45f8e81a903a7fdaad174f3a109c6265 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/cloudflare-web.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=65d608f2bf2863ac2f5eb410a011f9e8 2500w" />
    </Frame>

    <Note>
      Cloudflare's free Universal SSL certificates only cover the apex domain and one subdomain level. For multiple subdomain levels, you'll need an [Advanced Certificate](https://developers.cloudflare.com/ssl/edge-certificates/advanced-certificate-manager/manage-certificates/).
    </Note>
  </Step>

  <Step title="Update Configuration Files">
    Update your domain settings in the appropriate environment configuration files:

    For API service:

    <CodeGroup>
      ```yaml deploy/app/api/production.yaml theme={null}
      service: api
      port: 3001
      domain: api.my-ship-app.paralect.com
      ```

      ```yaml deploy/app/api/staging.yaml theme={null}
      service: api
      port: 3001
      domain: api.my-ship-app.staging.paralect.com
      ```
    </CodeGroup>

    For Web service:

    <CodeGroup>
      ```yaml deploy/app/web/production.yaml theme={null}
      service: web
      port: 3002
      domain: my-ship-app.paralect.com
      ```

      ```yaml deploy/app/web/staging.yaml theme={null}
      service: web
      port: 3002
      domain: my-ship-app.staging.paralect.com
      ```
    </CodeGroup>
  </Step>
</Steps>

## MongoDB Atlas

[MongoDB Atlas](https://cloud.mongodb.com/) is a fully managed cloud database service that provides automated backups, scaling, and security features. It offers 99.995% availability with global deployment options and seamless integration with AWS infrastructure.

### Cluster Creation

<Steps>
  <Step title="Access MongoDB Atlas">
    Sign in to your [MongoDB Atlas account](https://cloud.mongodb.com/) and create a new project if needed.
  </Step>

  <Step title="Deploy New Cluster">
    Click **Create** to start cluster deployment.

    **Cluster Tier Selection:**

    * **Staging**: `M0` (Free tier) - Suitable for development and testing
    * **Production**: `M10` or higher - Includes automated backups and advanced features

    {provider_1 === 'aws' && (
          <div>
            <p><strong>Provider & Region:</strong></p>
            <ul>
              <li>Select <strong>AWS</strong> as your cloud provider</li>
              <li>Choose the <strong>same region</strong> as your EKS cluster for optimal performance</li>
            </ul>
          </div>
        )}

    {provider_1 === 'do' && (
          <div>
            <p><strong>Provider & Region:</strong></p>
            <ul>
              <li>Select <strong>AWS</strong> as your cloud provider</li>
              <li>Choose the <strong>region closest</strong> to your Digital Ocean cluster for optimal performance</li>
            </ul>
          </div>
        )}

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=12e0f3723a43957b09f9f997b5554b63" alt="Deploy MongoDB Atlas cluster" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/deploy-cluster.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cfb12e79df6ea845ffb0aa615434ecf7 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bf5a003fd3a8f3ca4c3ffba6e9ab6db0 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8e2c72357b422c264b20fe7c1fd36075 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cd6b61eb75bf6ef937868c94ac9a421d 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8278428381d14224fd01ed516c514ff9 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/deploy-cluster.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=19210f154cfd38dc259adbf5e5c76fd8 2500w" />
    </Frame>
  </Step>

  <Step title="Configure Cluster Name">
    Enter a descriptive cluster name (e.g., `ship-production-cluster`, `ship-staging-cluster`)
  </Step>
</Steps>

### Security Configuration

<Steps>
  <Step title="Create Database User">
    Navigate to **Database Access** → **Add New Database User**

    * **Authentication Method**: Password
    * **Username**: Use environment-specific names (e.g., `api-production`, `api-staging`)
    * **Password**: Generate a strong password
    * **Database User Privileges**: **Read and write to any database**

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d9ba39fe38521e971b70bd34d43ab752" alt="Add MongoDB database user" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/add-database-user.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=68544cba438ccb44c7be67ec7ad5cefb 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f53199d693721e1882126a1496e405e1 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=423f8ddb9c421170db524d2052d43b84 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=860bbd0fba9f718f10eeaa33b3810410 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5ee12fa84f74040e2e08e6ea3cc11917 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/add-database-user.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8c74692cd49fff030294bde2007e41e4 2500w" />
    </Frame>

    <Warning>
      **Password Requirements**: Ensure the password starts with a letter and contains only alphanumeric characters and common symbols. Special characters at the beginning can cause URI parsing issues.
    </Warning>
  </Step>

  <Step title="Configure Network Access">
    Navigate to **Network Access** → **Add IP Address**

    * Click **Allow access from anywhere** to allow connections from any IP with valid credentials
    * For production, consider restricting to specific IP ranges for enhanced security

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=54cc00ef5fc768a1753dd1335f850cd6" alt="Configure MongoDB network access" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/network-access.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=dccabf32819369c563ab5b165136c694 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4c3c48d8e784535cfe66ddb687b6be70 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8ac03225a4bfd3baa71f89c9bf58e666 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e52ab68ea3d07aeef22a15302fb7b1c6 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d29f40ab52a77e6fd8c34260c0867dbb 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/network-access.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=649aef9f4962561fbf5f1a9355659422 2500w" />
    </Frame>
  </Step>
</Steps>

### Get Connection String

<Steps>
  <Step title="Access Connection Details">
    Go to your cluster dashboard and click the **Connect** button.

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=04932b0500406004a25474f27ec3ff03" alt="MongoDB Atlas dashboard" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/dashboard.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=73196c72d85645c47ed7338771305aa8 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=53e6457f582eb635a10baffab829717b 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=85269ac775d8edf077a4c92811276d2d 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c61bf29216d7982a60109736dc9b8232 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5f3742b38ac3f817d9d5d050be62b5b9 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/dashboard.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=3480e0905f009210c0c4252bbba7d7ca 2500w" />
    </Frame>
  </Step>

  <Step title="Copy Connection String">
    1. Select **Drivers** in the "Connect your application" section
    2. Choose **Node.js** driver and latest version
    3. Copy the connection string and replace `<db_password>` with your actual password

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4ecb740161946dfd461a2ba977fe5202" alt="MongoDB connection string" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/mongodb-cloud/cluster-connect.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c323ba15591da81637947314c3045e04 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a407cf450558d2348b27dfc239de8c4c 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ad0eec2c14d3ad3bdba60065bf721576 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b1a23603d2f7cceb667f82c8aafd1b49 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cf9d64963ad407c31f9a085aa2ec49bc 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongodb-cloud/cluster-connect.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=886d43dc8551d619cc52a9c522c0e25e 2500w" />
    </Frame>

    **Example Connection String:**

    ```bash  theme={null}
    mongodb+srv://api-production:your-password@cluster0.xxxxx.mongodb.net/?retryWrites=true&w=majority
    ```
  </Step>

  <Step title="Save Connection Details">
    Store the connection string securely - you'll need it for environment configuration later
  </Step>
</Steps>

<Tip>
  Before deploying to production, configure [automated backups](https://www.mongodb.com/docs/atlas/backup-restore-cluster/) in the Atlas console to ensure data recovery capabilities.
</Tip>

# Environment variables

Kubernetes applications require proper environment variable configuration for both API and Web components. This section covers how to set up and manage environment variables securely using Kubernetes secrets and configuration files.

### API Environment Variables

For the API deployment, you need to set up environment variables using Kubernetes secrets to securely manage sensitive configuration data.

<Info>
  **Secrets** in Kubernetes are used to store sensitive information, such as passwords, API tokens, and keys.
  They are encoded in Base64 format to provide a level of security.
  These can be mounted into containers as data volumes or used as environment variables.
</Info>

Before deploying the app, make sure all necessary variables from the API config are exist. Here are the minimal set of required variables:

| Name            | Description                | Example value                                      |
| --------------- | -------------------------- | -------------------------------------------------- |
| `APP_ENV`       | Application environment    | `production`                                       |
| `MONGO_URI`     | Database connection string | `mongodb://<username>:<password>@ship.mongodb.net` |
| `MONGO_DB_NAME` | Database name              | `api-production`                                   |
| `API_URL`       | API domain URL             | `https://api.my-ship-app.paralect.com`             |
| `WEB_URL`       | Web app domain URL         | `https://my-ship-app.paralect.com`                 |

#### Environment Variable Details

<Accordion title="APP_ENV">
  Specifies the application environment (development, staging, production). This controls logging levels, debugging features, error reporting, and other environment-specific behaviors. The API uses this to determine which configuration settings to load.
</Accordion>

<Accordion title="MONGO_URI">
  MongoDB connection string including authentication credentials and cluster information. This is the primary database connection for the API. Format: `mongodb+srv://username:password@cluster.mongodb.net`. Each environment should use a separate database cluster or at minimum separate credentials.
</Accordion>

<Accordion title="MONGO_DB_NAME">
  Name of the MongoDB database to use for this environment. Each environment (development, staging, production) should have its own database to prevent data conflicts and ensure proper isolation.
</Accordion>

<Accordion title="API_URL">
  The fully qualified domain name where the API will be accessible. This must be a valid HTTPS URL and should match your Kubernetes ingress configuration. Used for CORS settings and internal service communication.
</Accordion>

<Accordion title="WEB_URL">
  The fully qualified domain name where the web application will be accessible. Used for CORS configuration, redirect URLs, email templates, and social sharing metadata. Must be a valid HTTPS URL.
</Accordion>

#### Setting up Kubernetes Secrets

<Steps>
  <Step title="Create namespaces and secret objects">
    Create Kubernetes namespaces and secret objects for staging and production environments:

    ```bash  theme={null}
    kubectl create namespace staging
    kubectl create secret generic api-staging-secret -n staging
    kubectl create namespace production
    kubectl create secret generic api-production-secret -n production
    ```
  </Step>

  <Step title="Initialize secret storage">
    First, create an `APP_ENV` variable to initialize secret storage for k8sec:

    <CodeGroup>
      ```bash production theme={null}
      k8sec set api-production-secret APP_ENV=production -n production
      ```

      ```bash staging theme={null}
      k8sec set api-staging-secret APP_ENV=staging -n staging
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify secret creation">
    Run the following command to check the created secret:

    <CodeGroup>
      ```bash production theme={null}
      k8sec list api-production-secret -n production
      ```

      ```bash staging theme={null}
      k8sec list api-staging-secret -n staging
      ```
    </CodeGroup>
  </Step>

  <Step title="Prepare environment file">
    Create a `.env.production` file with all required variables:

    <CodeGroup>
      ```bash .env.production theme={null}
      APP_ENV=production
      MONGO_URI=mongodb://username:password@ship.mongodb.net
      MONGO_DB_NAME=api-production
      API_URL=https://api.my-ship-app.paralect.com
      WEB_URL=https://my-ship-app.paralect.com
      ```

      ```bash .env.staging theme={null}
      APP_ENV=staging
      MONGO_URI=mongodb://username:password@ship.mongodb.net
      MONGO_DB_NAME=api-staging
      API_URL=https://api.my-ship-app.staging.paralect.com
      WEB_URL=https://my-ship-app.staging.paralect.com
      ```
    </CodeGroup>

    <Warning>
      Replace all example values with your actual configuration. Never use production secrets in documentation or version control.
    </Warning>
  </Step>

  <Step title="Import secrets to Kubernetes">
    Import secrets from the .env file to Kubernetes secret using k8sec:

    <CodeGroup>
      ```bash production theme={null}
      k8sec load -f .env.production api-production-secret -n production
      ```

      ```bash staging theme={null}
      k8sec load -f .env.staging api-staging-secret -n staging
      ```
    </CodeGroup>
  </Step>
</Steps>

<Warning>
  After updating environment variables, you must initiate a new deployment for changes to take effect.
  Kubernetes pods cache variable values during startup, requiring a pod restart or rolling update to apply changes.
</Warning>

### Web Environment Variables

The web application uses Next.js environment variables that are embedded at build time and made available in the browser. Unlike API secrets, these variables are stored directly in the GitHub repository.

<Info>
  **Why Web Environment Variables Are Safe in Git**: Web environment variables (prefixed with `NEXT_PUBLIC_`) contain only public configuration like URLs and API endpoints. They don't include sensitive data like passwords or API keys, making them safe to store in version control. These values are already exposed to users in the browser, so repository storage doesn't create additional security risks.
</Info>

<Warning>
  **Security Notice**: Never store sensitive information (passwords, API keys, secrets) in web environment files as they will be accessible on the client side. Only use public configuration values that are safe to expose to end users.
</Warning>

#### Configuration Files

Web environment variables are stored in separate files for each deployment environment:

<CodeGroup>
  ```bash apps/web/.env.production theme={null}
  NEXT_PUBLIC_API_URL=https://api.my-ship-app.paralect.com
  NEXT_PUBLIC_WS_URL=https://api.my-ship-app.paralect.com
  NEXT_PUBLIC_WEB_URL=https://my-ship-app.paralect.com
  ```

  ```bash apps/web/.env.staging theme={null}
  NEXT_PUBLIC_API_URL=https://api.my-ship-app.staging.paralect.com
  NEXT_PUBLIC_WS_URL=https://api.my-ship-app.staging.paralect.com
  NEXT_PUBLIC_WEB_URL=https://my-ship-app.staging.paralect.com
  ```
</CodeGroup>

#### Environment Variables Reference

| Variable              | Description                          | Example                                |
| --------------------- | ------------------------------------ | -------------------------------------- |
| `NEXT_PUBLIC_API_URL` | Base URL for API requests            | `https://api.my-ship-app.paralect.com` |
| `NEXT_PUBLIC_WS_URL`  | WebSocket server URL for real-time   | `https://api.my-ship-app.paralect.com` |
| `NEXT_PUBLIC_WEB_URL` | App's own URL for redirects/metadata | `https://my-ship-app.paralect.com`     |

<Tip>
  **Best Practice**: Keep web environment files in your repository and ensure all values are non-sensitive. If you need to reference sensitive data from the frontend, create a secure API endpoint that returns the necessary information after proper authentication.
</Tip>

## Setting up GitHub Actions CI/CD

To automate deployment through Github Actions you need to configure [Github Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets) inside workflow files.

### Configuring GitHub Actions secrets and variables

<Note>
  Before starting, make sure you have created a GitHub repository for your project.
</Note>

GitHub Secrets and variables allow you to manage reusable configuration data.

Secrets are encrypted and are used for sensitive data. [Learn more about encrypted secrets](https://docs.github.com/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets).

Variables are shown as plain text and are used for non-sensitive data. [Learn more about variables](https://docs.github.com/actions/learn-github-actions/variables).

<Tip>
  The deployment will be triggered on each commit:

  * Commits to **main** branch → deploy to **staging** environment
  * Commits to **production** branch → deploy to **production** environment
</Tip>

[Configure](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) the following secrets and variables in your GitHub repository:

| Name                        | Type     | Description                                                                                                       |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| DO\_PERSONAL\_ACCESS\_TOKEN | secret   | The secret access user created for CI/CD. This allows GitHub Actions to authenticate with DO services             |
| CLUSTER\_NAME\_STAGING      | variable | Name of the staging cluster. (our case: `my-ship-app`)                                                            |
| CLUSTER\_NAME\_PRODUCTION   | variable | Name of the production cluster. (our case: `my-ship-app`, same as staging cluster since we have only one cluster) |
| CLUSTER\_NODE\_POOL         | variable | Name of the node pool. (our case: `pool-app`)                                                                     |
| REGISTRY\_NAME              | variable | Name of the Digital Ocean Container Registry. (our case: `my-ship-app`)                                           |

<Warning>
  Never commit sensitive credentials directly to your repository. <br />
  Always use GitHub Secrets for sensitive information like DO keys.
</Warning>

<Note>
  Variables (unlike secrets) are visible in logs and can be used for non-sensitive configuration values that may need to be referenced or modified.
</Note>

<Note>
  We set up **DO\_PERSONAL\_ACCESS\_TOKEN** to be universal for both production and staging environments with **Full access** scope.
</Note>

<Note>
  Your **KUBE\_CONFIG\_PRODUCTION** and **KUBE\_CONFIG\_STAGING** will be the same if you have only one cluster for both environments.
</Note>

<Frame>
  <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-secrets.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f22e3a8c208ab234e5ddb3b64fbe4799" alt="GitHub Secrets" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/do/gh-secrets.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-secrets.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f1d664eb75f48331ec38de304d010193 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-secrets.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d38bff11c396475177c0cf8838cc250c 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-secrets.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=3c040033046fe9556b91ceaeed7195d6 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-secrets.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ab48588840112692aea73d18a63fda01 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-secrets.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ef5669ab05fad657045f65903933674d 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-secrets.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=77f891391460158de7f402c0997b81f0 2500w" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-variables.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=5756f0a04edd763aed18aa06283ac5da" alt="GitHub Variables" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/do/gh-variables.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-variables.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f15fab5a94d88e983828e9f61d3649dd 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-variables.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=448d8317f1b880ad3622bf27f00a79ec 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-variables.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b5c6b9e451d8a612158d51cf6b35ca3b 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-variables.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9e4e9eeb1875cf390d133896ea81d0d7 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-variables.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4ff1c801b68f2387025d4fceba02052e 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/gh-variables.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=493cebd23b81b7c3bed3513dc7475d7c 2500w" />
</Frame>

Now commit all changes to GitHub that will trigger deployment, or you can [run a workflow manually](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow)

<Frame>
  <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-start.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bf3f7f7be216469dd91340dd8ab06d66" alt="CI start" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/do/ci-start.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-start.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=383bd90e3f7d378aa2c364308a17db1d 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-start.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=35c6c2873144834217212e46ec8b02bb 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-start.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=bcdb003ba6b6e836744bfc4321e1001c 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-start.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=cfc3f80951ef5e7c35ce821b677ab603 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-start.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=36d3e933172e6851890242fe9d4f61f1 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-start.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=02c97286240f11e7e03b8cb40b11339a 2500w" />
</Frame>

Done! Application deployed and can be accessed by the provided domain.

<Frame>
  <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-finish.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=0d193c7c09f5b432fdf60cd3cb095e6e" alt="CI finish" data-og-width="7680" width="7680" data-og-height="4320" height="4320" data-path="images/do/ci-finish.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-finish.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c79f792545320b14ec69f02248947b10 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-finish.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=4ebe08a1e26e53ae46ad009b513a3a93 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-finish.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=cc5ff33ab27910b6785e86699e6b5d32 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-finish.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c1ff59f082c816a9b704e137f2327018 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-finish.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a473cb7f3b6ed9cdd468c11447b73486 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/ci-finish.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=70fd34be8636a10a855830231378dd79 2500w" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/deployment-finish.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=26c0f33997a075100e8b28fc47b8d108" alt="Deployment finish" data-og-width="1920" width="1920" data-og-height="979" height="979" data-path="images/do/deployment-finish.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/deployment-finish.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=26a03829db5c03fe69ea0b43d6ed8492 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/deployment-finish.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=039c6c1c6abf5e513c304bb80540680e 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/deployment-finish.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=61dce74c998eacc2ec3fe42468d0a73d 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/deployment-finish.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b6c9fe85b7d8d73df1de629274b9fdd3 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/deployment-finish.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=eb982d7ee443b32326e2d303d944c902 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/do/deployment-finish.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f3f0103cd029e306559b875b95a0d94a 2500w" />
</Frame>

```shell  theme={null}
kubectl get pods -A

NAMESPACE       NAME                                        READY   STATUS      RESTARTS   AGE
ingress-nginx   ingress-nginx-controller-6bdff8c8fd-kwxcn   1/1     Running     0          6h50m
kube-system     cilium-tb8td                                1/1     Running     0          8h
kube-system     cilium-x5w8n                                1/1     Running     0          8h
kube-system     coredns-5679ffb5c8-b7dzj                    1/1     Running     0          8h
kube-system     coredns-5679ffb5c8-d465r                    1/1     Running     0          8h
kube-system     cpc-bridge-proxy-ebpf-2gzfr                 1/1     Running     0          8h
kube-system     cpc-bridge-proxy-ebpf-jknzh                 1/1     Running     0          8h
kube-system     csi-do-node-jcqd2                           2/2     Running     0          8h
kube-system     csi-do-node-rpx6q                           2/2     Running     0          8h
kube-system     do-node-agent-ldhxq                         1/1     Running     0          8h
kube-system     do-node-agent-pdksz                         1/1     Running     0          8h
kube-system     hubble-relay-66f54dcd57-l7xjb               1/1     Running     0          8h
kube-system     hubble-ui-785bdbc45b-6xd57                  2/2     Running     0          8h
kube-system     konnectivity-agent-h79mt                    1/1     Running     0          8h
kube-system     konnectivity-agent-hvv67                    1/1     Running     0          8h
production      api-57d7787d98-cj75s                        1/1     Running     0          2m15s
production      migrator-286bq                              0/1     Completed   0          2m54s
production      scheduler-6c497dfbcc-n6b5l                  1/1     Running     0          2m6s
production      web-54c6674974-lv94b                        1/1     Running     0          71m
redis           redis-master-0                              1/1     Running     0          6h49m
staging         api-689b75c786-97c4l                        1/1     Running     0          71m
staging         scheduler-57b984f6c-zcc44                   1/1     Running     0          71m
staging         web-55bdd955b-chswp                         1/1     Running     0          70m
```

<Tip>
  If something went wrong you can check the workflows logs on GitHub and use [**kubectl logs**](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#interacting-with-running-pods), [**kubectl describe**](https://kubernetes.io/docs/reference/kubectl/cheatsheet/#viewing-finding-resources) commands.
</Tip>

## Setting up Upstash Redis database (recommended)

# Upstash Redis Integration

[Upstash Redis](https://upstash.com/) is a **highly available, infinitely scalable** Redis-compatible database that provides enterprise-grade features without the operational complexity.

## How Ship Uses Redis

Ship leverages Redis for several critical functionalities:

| Use Case                    | Description                                       | Implementation                                                      |
| --------------------------- | ------------------------------------------------- | ------------------------------------------------------------------- |
| **Real-time Communication** | Pub/Sub mechanism for WebSocket functionality     | [Socket.io Redis Adapter](https://socket.io/docs/v4/redis-adapter/) |
| **Rate Limiting**           | API request throttling and abuse prevention       | Redis counters with TTL                                             |
| **Caching**                 | Application data caching for improved performance | Key-value storage with expiration                                   |

<Info>
  **Redis as a Message Broker**: When scaling to multiple server instances, Redis acts as a message broker between Socket.io servers, ensuring real-time messages reach all connected clients regardless of which server they're connected to.
</Info>

## Setting Up Upstash Redis

### Create Your Database

<Steps>
  <Step title="Access Upstash Console">
    Log in to your [Upstash account](https://console.upstash.com/) and navigate to the Redis section.
  </Step>

  <Step title="Create New Database">
    Click **Create Database** in the upper right corner to open the configuration dialog.

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c7797ba6b2a8538f611365d30d553c7e" alt="Create Upstash Redis Database" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/upstash-redis/create-global.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5b7a389c8d214bc071a66198668abe3d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7d1c21021d77ef784502bd42e0d34527 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=75369756145d7d2d776587624eff70ce 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ab63aa595dcea30cd127a57ec648f030 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4eb03d1621b7945054d2fc95e99e200c 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/create-global.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1f5a79ac57a43abdd12f27bf6f08033b 2500w" />
    </Frame>
  </Step>

  <Step title="Configure Database Settings">
    **Database Name:** Choose a descriptive name for your database (e.g., `my-ship-app-production`)

    **Primary Region:** Select the region closest to your main application deployment for optimal write performance.

    **Read Regions:** Choose additional regions where you expect high read traffic for better global performance.
  </Step>

  <Step title="Select Plan & Deploy">
    Choose your pricing plan based on expected usage and click **Create** to deploy your database.
  </Step>
</Steps>

<Tip>
  {provider_0 === 'aws' && (
      <p>
        <strong>Region Selection:</strong> For Kubernetes deployments on AWS, choose the same AWS region as your EKS cluster to minimize latency and data transfer costs.
      </p>
    )}

  {provider_0 === 'do' && (
      <p>
        <strong>Region Selection:</strong> For Kubernetes deployments on Digital Ocean, choose the same region as your cluster to minimize latency and data transfer costs.
      </p>
    )}
</Tip>

Once your database is created, you'll need the connection string for your application:

<Steps>
  <Step title="Navigate to Connection Info">
    Go to your database dashboard and find the **Connect to your database** section.

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=9705f2cee3b707820948d3eec2f08734" alt="Upstash Redis Connection Details" data-og-width="2880" width="2880" data-og-height="1800" height="1800" data-path="images/upstash-redis/database.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=82c1b77e1af7b30332799d149b745146 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=3ff403da9211a59291dbf8637932b5a8 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=fff28964c02ef9da805ee49a6d64f34c 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=3c0e99bd0e2a14df3ba14e702ca294ef 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=796fc214062d077d94d429d026a55a6d 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/database.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=9a9ffcd82f4eae9a5bfbc2b9151ce375 2500w" />
    </Frame>
  </Step>

  <Step title="Copy Connection String">
    1. Select the **Node** tab for the appropriate connection string format
    2. Click **Reveal** to show the hidden password
    3. Copy the complete Redis URI (format: `rediss://username:password@host:port`)
  </Step>

  <Step title="Add to Environment Variables through k8sec">
    Using `k8sec`, add the Redis connection string to your environment configuration:

    <CodeGroup>
      ```bash production theme={null}
      k8sec set api-production-secret -n production REDIS_URI=$REDIS_URI
      ```

      ```bash staging theme={null}
      k8sec set api-staging-secret -n staging REDIS_URI=$REDIS_URI
      ```
    </CodeGroup>

    <Note>
      After updating environment variables, restart your API pod using:

      ```bash  theme={null}
      kubectl delete pod <pod-name> -n <namespace>
      ```

      This will trigger Kubernetes to create a new pod with the updated environment variables.
    </Note>
  </Step>
</Steps>

### Verify Connection with Redis Insight

Redis Insight is a powerful GUI tool for managing and debugging Redis databases.

<Steps>
  <Step title="Install Redis Insight">
    Download and install [Redis Insight](https://redis.io/insight/) on your local machine.
  </Step>

  <Step title="Add Database Connection">
    1. Open Redis Insight
    2. Click **Add Database**
    3. Paste your Upstash Redis connection string in the **Connection URL** field
    4. Click **Add Database**

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=dc5072c3077144b8c0ebd997c1595074" alt="Redis Insight Connection Setup" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/upstash-redis/redis-insight.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7d7b1d2063b3d8e22dd1b286771a9b25 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=083f32d2ed3b0c958d75210820df995b 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=fc6d38ddd7396e9588d5e95f5392df56 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e3b4ae2d98c46bf9cb9358401ec3e611 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=60b52d55861635b2c16bf10098777df5 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/redis-insight.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ee88e812ad858956387d744c92a811e2 2500w" />
    </Frame>
  </Step>

  <Step title="Explore Your Database">
    Once connected, you can use Upstash Redis Console to:

    * Browse keys and data structures
    * Execute Redis commands directly
    * Monitor real-time performance metrics
    * Debug application data storage

    <Frame>
      <img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a5bc78e23381ab469980479d247270b8" alt="Upstash Redis Metrics Dashboard" data-og-width="1271" width="1271" data-og-height="279" height="279" data-path="images/upstash-redis/charts.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=546f6728b651e70cb51169f9c42f3be4 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6694a5c3f6e6d26b9dd6193d1fc76dc2 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=677dc96a96a9621074bc7857d9ffdfe3 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bd722d61192a9e2be9b51794f748ea3c 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4fed9af7f4496af0179e3fedf6761435 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/upstash-redis/charts.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cad48a52efeed8e0513abe1e64cc4719 2500w" />
    </Frame>

    <Info>
      **Real-time Monitoring**: Upstash Redis updates database metrics automatically every 10 seconds, giving you near real-time visibility into your Redis performance and usage.
    </Info>
  </Step>
</Steps>


# Overview
Source: https://ship.paralect.com/docs/deployment/kubernetes/overview



We use the next primary technologies for deployment:

* [Docker](https://www.docker.com/) for delivering applications inside containers;
* [Kubernetes](https://kubernetes.io/) for containers orchestration;
* [Helm](https://helm.sh/) for managing Kubernetes applications;
* [GitHub Actions](https://github.com/features/actions) for CI/CD deployment;

To use this guide we highly recommend you to check their documentation and be familiar with basics.

Deployed application is multiple services, wrapped in Docker containers and run inside the Kubernetes cluster.
Ship consists of 4 services by default: [**Web**](/web/overview), [**API**](/api-reference/overview), [**Scheduler**](/scheduler) and [**Migrator**](/migrator).

Deployment can be done manually from your local machine or via a CI/CD pipeline.
We have templates of deployment scripts for Digital Ocean and AWS, but you can use another cloud providers with minor changes.

## External services you need

* Kubernetes cluster, you can create [DO Managed Kubernetes](https://www.digitalocean.com/products/kubernetes) or [AWS EKS](https://aws.amazon.com/eks/);
* Container registry for your Docker images, mostly cloud providers has it own: [DO Container Registry](https://www.digitalocean.com/products/container-registry), [AWS ECR](https://aws.amazon.com/ecr/);
* DNS provider account. We recommend [CloudFlare](https://www.cloudflare.com/), for AWS you can use [Route 53](https://aws.amazon.com/route53/);
* Managed MongoDB. We recommend [MongoDB Atlas](https://www.mongodb.com/atlas/database) or [DO Managed MongoDB](https://www.digitalocean.com/products/managed-databases-mongodb);

## Deployment schema

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/deployment-schema.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=34b8d570f1e7e04214b3c550bb41911c" alt="Deployment schema" data-og-width="1750" width="1750" data-og-height="2152" height="2152" data-path="images/deployment-schema.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/deployment-schema.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f892eb929c4f8de4371895f16356bd3e 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/deployment-schema.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=da8e2619549dd6bf91fae5854e21c9bc 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/deployment-schema.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d6faabe8d78d141b962871c18bb54df3 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/deployment-schema.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=59bbff02ad46e783f4065b97d787e1c0 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/deployment-schema.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a26dd74fad70d19d03506382b6957f61 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/deployment-schema.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=e3c04b7d90a237d3519b863bbe5495ba 2500w" />

## Deployment flow

The deployment flow is pretty simple. Once you make changes in any service, the script builds a new Docker image for it, adds **image tag** to it, and pushes it to the Container Registry.

Script passes the image tag to deployment command, so Kubernetes knows which image needs to be downloaded from the registry. Image tag consists of repo branch and commits hash.

```shell  theme={null}
imageTag = `${branch}.${commitSHA}`;
```

Then script grabs all resources templates([Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/), [Service](https://kubernetes.io/docs/concepts/services-networking/service/), etc) from the [templates](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/deploy/app/api/templates) folder for services that are deploying, packages them as [Helm Chart](https://helm.sh/docs/topics/charts/), and creates [Helm Release](https://helm.sh/docs/intro/using_helm/#three-big-concepts) that installs all that resources in the cluster. During the release, Kubernetes will download a new Docker image from registry and use it to create a new version of the service in the cluster.

<Tip>
  We use [**Blue-Green**](https://martinfowler.com/bliki/BlueGreenDeployment.html) deployment through [**Rolling Update**](https://kubernetes.io/docs/tutorials/kubernetes-basics/update/update-intro/).
</Tip>

This is the main part of the deployment script.

```javascript deploy/script/src/index.js theme={null}
const buildAndPushImage = async ({ dockerFilePath, dockerRepo, dockerContextDir, imageTag, environment }) => {
  await execCommand(`docker build \
    --build-arg APP_ENV=${environment} \
    -f ${dockerFilePath} \
    -t ${dockerRepo} \
    ${dockerContextDir}`);
  await execCommand(`docker tag ${dockerRepo} ${imageTag}`);
  await execCommand(`docker push ${imageTag}`);
}

const pushToKubernetes = async ({ imageTag, appName, deployConfig }) => {
  await execCommand(`
    helm upgrade --install apps-${config.environment}-${appName} ${deployDir} \
      --namespace ${config.namespace} --create-namespace \
      --set appname=${appName} \
      --set imagesVersion=${imageTag} \
      --set nodePool=${config.nodePool} \
      --set containerRegistry=${config.dockerRegistry.name} \
      -f ${deployDir}/${config.environment}.yaml \
      --timeout 35m \
  `);
}

// build web image and push it to registry
await buildAndPushImage({
  ...deployConfig,
  imageTag: `${deployConfig.dockerRepo}:${imageTag}`,
  environment: config.environment
});

// deploy web to kubernetes
await pushToKubernetes({
  imageTag,
  appName: 'web',
  deployConfig
});

```

We have 2 separate GitHub Actions [workflows](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions) for services:

* Deploy [**Web**](/web/overview)
* Deploy [**API**](/api-reference/overview), [**Scheduler**](/scheduler), and [**Migrator**](/migrator). Migrator deploys **before** API and Scheduler.

If the Migrator fails, API and Scheduler will be not deployed. This approach guarantees us that the API and Scheduler always work with the appropriate database schema.

<Tip>
  We have [**separate**](https://github.com/paralect/ship/tree/main/deploy/digital-ocean/.github/workflows) GitHub Actions workflows for different environments.
</Tip>

## Environment variables

When deploying "Ship" to Kubernetes, it's essential to consider the configuration needs of different environments.
By separating the environment-specific settings into dedicated files,
you can easily manage and deploy the application across environments.

The `APP_ENV` environment variable is typically set based on the environment in which the application is running.
Its value corresponds to the specific environment, such as "development", "staging" or "production".
This variable helps the application identify its current environment and load the corresponding configuration.

For the web application, by setting the environment variable `APP_ENV`,
the application can determine the environment in which it is running and download the appropriate configuration file:

| APP\_ENV    | File             |
| ----------- | ---------------- |
| development | .env.development |
| staging     | .env.staging     |
| production  | .env.production  |

These files should contain specific configuration variables required for each environment.

In contrast, the API utilizes a single `.env` file that houses its environment-specific configuration.
This file typically contains variables like API keys, secrets, or other sensitive information.
To ensure security, it's crucial to add the `.env` file to the `.gitignore` file,
preventing it from being tracked and committed to the repository.

When deploying to Kubernetes,
you'll need to include the appropriate environment-specific configuration files in your deployment manifests.
Kubernetes offers [**ConfigMaps**](https://kubernetes.io/docs/concepts/configuration/configmap/) and [**Secrets**](https://kubernetes.io/docs/concepts/configuration/secret/)
for managing such configurations.

**ConfigMaps** are suitable for non-sensitive data,
while **Secrets** are recommended for sensitive information like API keys or database connection string.
Ensure that you create **ConfigMaps** or **Secrets** in your Kubernetes cluster
corresponding to the environment-specific files mentioned earlier.

## Database setup

We recommend avoiding self-managed database solutions and use cloud service like [MongoDB Atlas](https://www.mongodb.com/atlas/database) that provides managed database. It handles many quite complex things: database deployment, backups, scaling, and security.

## SSL

To make your application work in modern browsers and be secure, you need to configure SSL certificates.
The easiest way is to use [CloudFlare](https://www.cloudflare.com/), it allows you to set up SSL in most simple way by proxying all traffic through CloudFlare. Use this [guide](https://developers.cloudflare.com/fundamentals/get-started/setup/add-site/).

Cloudflare can be used as DNS nameservers for your DNS registrar, such as [GoDaddy](https://www.godaddy.com/). Also, you can buy and register a domain in Cloudflare itself.

If you are deploying in AWS you can use [AWS Certificate Manager](https://aws.amazon.com/ru/certificate-manager/) for SSL.

## Services

Services are parts of your application packaged as Helm Charts.

| Service                                                                                     | Description                                                                                                                             | Kubernetes Resource |
| :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
| [**Web**](https://github.com/paralect/ship/blob/main/template/apps/web)                     | Next.js server that serves static files and API endpoints                                                                               | Pod                 |
| [**API**](https://github.com/paralect/ship/blob/main/template/apps/api)                     | Backend server                                                                                                                          | Pod                 |
| [**Scheduler**](https://github.com/paralect/ship/blob/main/template/apps/api/src/scheduler) | Service that runs cron jobs                                                                                                             | Pod                 |
| [**Migrator**](https://github.com/paralect/ship/blob/main/template/apps/api/src/migrator)   | Service that migrates database schema. It deploys before api through Helm pre-upgrade [hook](https://helm.sh/docs/topics/charts_hooks/) | Job                 |

To deploy services in the cluster manually you need to set cluster authorization credentials inside [config](https://github.com/paralect/ship/blob/main/examples/base/deploy/script/src/config.js) and run deployment [script](https://github.com/paralect/ship/blob/main/examples/base/deploy/script/src/index.js).

```shell deploy/script/src theme={null}
node index

? What service to deploy? (Use arrow keys)
  api
  web
```

When you will configure GitHub Secrets in your repo, GitHub Actions will automatically deploy your services on push in the repo.
You can check the required secrets inside [workflow](https://github.com/paralect/ship/tree/main/deploy/digital-ocean/.github/workflows) files.

<Tip>
  If you are adding new service, you need to configure it in [**app**](https://github.com/paralect/ship/blob/main/examples/base/deploy/app) and [**script**](https://github.com/paralect/ship/blob/main/examples/base/deploy/script/src) folders.
  You can do it following the example from neighboring services.
</Tip>

## Dependencies

Dependencies are third-party services packaged as Helm Charts and bash scripts that install configured resources in the cluster.

| Dependency                                                                                             | Description                                                                                                                                                                                                                            |
| :----------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [ingress-nginx](https://github.com/kubernetes/ingress-nginx)                                           | Ingress controller for Kubernetes using Nginx as a reverse proxy and load balancer                                                                                                                                                     |
| [redis](https://github.com/bitnami/charts/tree/main/bitnami/redis)                                     | Open source, advanced key-value store                                                                                                                                                                                                  |
| [regcred](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/deploy/dependencies/regcred) | Bash script for creating Kubernetes [Secret](https://kubernetes.io/docs/concepts/configuration/secret/). Secret needs for authorizing in Container Registry when pulling images from cluster. Required only for Digital Ocean clusters |

To deploy dependencies in cluster, you need to run [deploy-dependencies.sh](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/deploy/bin/deploy-dependencies.sh) script.

```shell deploy/bin theme={null}
bash deploy-dependencies.sh
```

<Tip>
  If you are adding new dependency, you need to create separate folder inside [**dependencies**](https://github.com/paralect/ship/blob/main/examples/base/deploy/dependencies) folder and configure new Chart.
  Also, you need to add new dependency in [**deploy-dependencies.sh**](https://github.com/paralect/ship/blob/main/examples/base/deploy/bin/deploy-dependencies.sh) script.
  You can do it following the example from neighboring dependencies.
</Tip>

## Deploy scripts structure

| Folder                                                                                              | Description                                                             |
| :-------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |
| [.github](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/.github/workflows)        | GitHub Actions CI/CD pipelines for automated deployment on push in repo |
| [app](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/deploy/app)                   | Helm charts for services                                                |
| [bin](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/deploy/bin)                   | Utils scripts                                                           |
| [dependencies](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/deploy/dependencies) | Helm charts for dependencies                                            |
| [script](https://github.com/paralect/ship/blob/main/deploy/digital-ocean/deploy/script)             | Deployment script                                                       |


# Render
Source: https://ship.paralect.com/docs/deployment/render



There is a simplified type of deployment where you can try to deploy Ship for free using [Render](https://render.com).
This type allows you to set up infrastructure faster and doesn't require additional DevOps knowledge from the development team.
You can switch to a more complex Kubernetes solution when your application will be at scale.

It's a step-by-step Ship deployment guide. We will use the [Render](https://render.com), [Mongo Atlas](https://www.mongodb.com/) and [Redis Cloud](https://redis.com/try-free/) for databases deployment and [Cloudflare](https://www.cloudflare.com/) **(optional)** for DNS and SSL configuration.

You need to create [GitHub](https://github.com/), [Render](https://render.com), [CloudFlare](https://www.cloudflare.com/), [MongoDB Atlas](https://www.mongodb.com/cloud/atlas/register) and [Redis Cloud](https://redis.com/try-free/) accounts.

Also, you need [git](https://git-scm.com/) and [Node.js](https://nodejs.org/en/) if you already haven't.

## Setup project

First, initialize your project. Type `npx create-ship-app init` in the terminal then choose desired build type and **Render** as a cloud service provider.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project-koa-render.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=5d3a4bdeacc3698c36c9caf78d84aab8" alt="Init project" data-og-width="682" width="682" data-og-height="483" height="483" data-path="images/init-project-koa-render.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project-koa-render.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ebb5cde3f2117b3a8a4a10530366e4db 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project-koa-render.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=87f48a2f9f332f69c454e0798ae1004a 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project-koa-render.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2517c2a4e872a03858ee018735e328fc 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project-koa-render.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=76cdbcc60199e7ffac571d6cde6600f3 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project-koa-render.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=295d3fa7119ba62208c93c92fe3004c6 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project-koa-render.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=17085495ad4bcaa3014bdbe844e15a4e 2500w" />

You will have next project structure.

```shell  theme={null}
/my-app
  /apps
    /web
    /api
  /.github
  ...
```

Create GitHub private repository and upload source code.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=99e9c308e537fa2147b9a42e45851b4a" alt="Private repo" data-og-width="3024" width="3024" data-og-height="1664" height="1664" data-path="images/private-repo.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e4ecbcae9fda0642835e99276f5d9f12 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a8a1cb981e3d6c45105bd096c2ce796d 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8d01a82b9505310b75ad01933948c685 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=46ab1ec791c8127191b7f9a3ec9d5fc1 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b862abab96dbd5d5d779bbe3d1bd126d 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/private-repo.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7c5a2c11bcc2bbee9888c41a7a72d3f6 2500w" />

```shell  theme={null}
cd my-app
git remote add origin https://github.com/Oigen43/my-app.git
git branch -M main
git push -u origin main
```

## MongoDB Atlas

Navigate to [MongoDB Atlas](https://cloud.mongodb.com/), sign in to your account and create a new database.

### Database creation

1. Select the appropriate type. Dedicated for a production environment, shared for staging/demo.
2. Select provider and region. We recommend selecting the same or closest region to the DO application.
3. Select cluster tier. Free M0 Sandbox should be enough for staging/demo environments. For production environment we recommended selecting the option that supports cloud backups, M2 or higher.
4. Enter cluster name

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8b72ad717dd384775352d370f925afb1" alt="Mongo cluster" data-og-width="893" width="893" data-og-height="683" height="683" data-path="images/mongo-create.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a5cb583512963f07931ef3f20c50118e 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=deb9a3ba46b6d9967730d1339ebc08ad 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8083ea5e764bd486f0c19a9b19d08d99 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=543a9128c203186f679d31fc2deeb129 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=008b31a0cdf4f7db5ba7736a8cbb8431 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-create.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=07a0029145d6b6f87a4d8a413ef332cd 2500w" />

### Security and connection

After cluster creation, you'll need to set up security. Select the authentication type (username and password) and create a user.

<Warning>
  Please be aware that the initial character of the generated password should be a letter. If it isn't, you'll need to create a new password.
  Failing to do this may lead to DigitalOcean parsing the `MONGO_URI` variable incorrectly.
</Warning>

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=9ce4c8b83b1b0f6d30908b1b7605ca0d" alt="Mongo setup authentication" data-og-width="859" width="859" data-og-height="665" height="665" data-path="images/mongo-create-password.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=c1d296cc086cd97af1574b45379ac3ad 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=629e743c08f46ac2df1d0d0fd374d424 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=ad4c9cd34242488aae734458bbe440c3 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dce96660ecfab2cd3b02a8e3b8980544 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1363cfda4a95ef6e29e2dee6e51b8972 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-password.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d6ce7c34e39a8e2f31796443faa56f2a 2500w" />

Add IP addresses list, which should have access to your cluster. Add 0.0.0.0/0 IP address to allow anyone with credentials to connect.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dec3cc10f4b5d050c3849a864940d685" alt="Mongo setup ip white list" data-og-width="798" width="798" data-og-height="585" height="585" data-path="images/mongo-create-ip-list.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=663c69bd75770aabe21d1e7f96f608c0 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=25d510ef958fd0dca57a43b6f1a9d6db 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1c0689de96ed85b87290b66325087586 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6afaa4b615e6d1100bc65a8830f0a50c 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=78dde2e2b1c6ea5be3691e2db6d2e76c 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-create-ip-list.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=acd0558df150e379f6ff611e22a09ba8 2500w" />

After database creation, go to the dashboard page and get the URI connection string by pressing the `connect` button.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ec62e0bc9535069f0515855ca5e8e734" alt="Mongo dashboard" data-og-width="2159" width="2159" data-og-height="718" height="718" data-path="images/mongo-dashboard.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e992cb11e0d3a88209a2e6c1e5a8a65f 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5775bf0eca9bab58fe8e2d7a009b9662 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d9f67c142d420322426817ce95d8288c 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b647872fe6b4bfeb4c9b71f33bb568e7 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e0e54fade38da1dc5341fba2ae045d1a 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/mongo-dashboard.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1c5d112ee9e3c51016f671e1cc7869e0 2500w" />

Select `Connect your application` option. Choose driver and mongo version, and copy connection string. Don't forget to replace `<password>` with your credentials.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=253397af19c0b6c843df2ef8a8df1e3d" alt="Mongo connect dialog" data-og-width="794" width="794" data-og-height="637" height="637" data-path="images/mongo-connection-string.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=2b664b7a181fa57766b811d5a43b8d36 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=d6aaa543aa485159c1906a2c58cbc30d 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=13637478ce4f5cee86a06ee7109f6a81 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=dbf4f374a54d08235f795ff479283aaa 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=92ded21ee9fa5863e3eb92a21def4129 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/mongo-connection-string.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6bb309ff6dd6630f310453bba784d44c 2500w" />

Save this value. It will be needed later when creating the app in Digital Ocean.

<Tip>
  Before moving to production, it's crucial to set up [MongoDB backup methods](https://www.mongodb.com/docs/manual/core/backups).

  This ensures that you can reliably restore your data in the event of unforeseen circumstances.
</Tip>

## Redis Cloud

Navigate to [Redis Cloud](https://redis.com/try-free/) and create an account. Select cloud provider and region, then press `Let's start free` to finish database creation.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a45dc74ec5ef9ab0fe1dba7e41b0cbf3" alt="Redis create database" data-og-width="953" width="953" data-og-height="581" height="581" data-path="images/redis-creation.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cf9a6246b47174257951e211f4afa9f3 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=20d53d657a6ba50efa8ec8f8a38fe246 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=182fdc95562f4e368d543bed1fe7a5b1 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bc7a420704e9c4806c3041027cb4b9e2 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=801bdbebeeb5b53696a6099154fd0165 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-creation.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f4e6ca180d429b459bb359bd3f223238 2500w" />

Open database settings and get the database public endpoint and password.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c9ea4f3ceed66d3150be43660aed728f" alt="Redis public endpoint" data-og-width="1601" width="1601" data-og-height="923" height="923" data-path="images/redis-public-endpoint.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6736ef62451c2e29c7c2ced3090cf88d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b9ec666b310ea81856c00606c1639b0e 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=69ddea5ec61e3c8a18b7704e9afda803 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1b7c34de212de19adee67847bda32714 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f36719c6398e4831c3bbac12c7f86e66 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-public-endpoint.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=af0e88e8f8b908430160cad3b0d39cd2 2500w" />
<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1914c1c31a6028b74820e10b3151da03" alt="Redis password" data-og-width="1573" width="1573" data-og-height="514" height="514" data-path="images/redis-password.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8031fef2cf9a78f1a614ccea80009544 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=2d06233dd94d077d88c83a58a819cfb0 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4eaa284a0b7fbd6383d4a77b474bdd04 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c0665f2cbaab668e8b475f75c70e0258 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=872a0beeb86ffe94ec83b1de255bd907 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/redis-password.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=73ec7e82a1786104d664c32e64c83fb0 2500w" />

Form Redis connection string using public endpoint and password `redis://:<password@<public-endpoint>`. Save this value. It will be needed later when creating the app in Digital Ocean.

## Render

Navigate to the [Render Dashboard Panel](https://dashboard.render.com/) and select the **Blueprints** tab.

The `Full-Stack` build type requires 2 applications. First for [Web](/web/overview) and second for [API](/api-reference/overview), [Migrator (TBD)](https://github.com/docs/migrator.md), and [Scheduler (TBD)](https://github.com/docs/scheduler.md) services.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-blueprints.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=23afcb5a50f1b65ba4f144637e87258c" alt="Render Blueprints Tab" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/render-blueprints.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-blueprints.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cdac29649dcde258dadf6977ce722f0e 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-blueprints.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=359fd58ebd9baa7f7080d36b01eff41b 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-blueprints.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1e73b6aa70ea2b5cdb96a592a2e37301 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-blueprints.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=fd669130dd95bab2fb00e67db48fc245 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-blueprints.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d01eaa058b712f94b5242b82c55bc0b4 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-blueprints.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=2a7ea93e4af301074bbc467af0b655b4 2500w" />

<Tip>
  Ship provides an easy way to deploy your applications using [Infrastructure as Code (IaC)](https://render.com/docs/infrastructure-as-code).

  You can learn more about [Blueprint Specification here](https://render.com/docs/blueprint-spec).
  Review your `render.yaml` file in the application root directory and make some corrections if necessary.
</Tip>

Click on the **New Blueprint Instance** button and **connect** the appropriate repository with Ship.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-create-blueprint-instance.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e7f7ac8f0de3e489f90779451c0f5a21" alt="Create a Blueprint instance" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/render-create-blueprint-instance.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-create-blueprint-instance.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1ef219ae03b87808036347fd7cc0ce5a 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-create-blueprint-instance.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=06290af482c79ed43f5cd8dad59cbd40 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-create-blueprint-instance.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a6f5b4f7624998095984b0cb1487921c 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-create-blueprint-instance.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=737d96a765114c7baea0cbe36b1ec3a4 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-create-blueprint-instance.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=97f7540aa396830639c473f71856ea40 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-create-blueprint-instance.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=75bcb12591ae8db9597dd4792ce56e81 2500w" />

Specify a name for your Blueprint instance, select a branch, and review the changes to apply them.
**Apply** changes if you are satisfied with everything.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-review-blueprint-creation.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=42034d9c181d4ddaf89fae988cef3029" alt="Review Blueprint Creation" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/render-review-blueprint-creation.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-review-blueprint-creation.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8daeeef40ec1722dc13a350532651982 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-review-blueprint-creation.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f427944f5c9da83117aa8756d3af7c77 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-review-blueprint-creation.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6bc1aec1121d54f0c01c612dc33b58fc 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-review-blueprint-creation.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=36bb4b543d778b4409e595a02c65c106 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-review-blueprint-creation.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=82f1a7cf51d1cfdc9faf7bd4cf2faead 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-review-blueprint-creation.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5ccfc556c4a5432ed3e13e03935e9d09 2500w" />

### Environment variables

The `APP_ENV` environment variable is typically set based on the environment in which the application is running.
Its value corresponds to the specific environment, such as "development", "staging" or "production".
This variable helps the application identify its current environment and load the corresponding configuration.

For the web application, by setting the environment variable `APP_ENV`,
the application can determine the environment in which it is running and download the appropriate configuration file:

| APP\_ENV    | File             |
| ----------- | ---------------- |
| development | .env.development |
| staging     | .env.staging     |
| production  | .env.production  |

These files should contain specific configuration variables required for each environment.

In contrast, the API utilizes a single `.env` file that houses its environment-specific configuration.
This file typically contains variables like API keys, secrets, or other sensitive information.
To ensure security, it's crucial to add the `.env` file to the `.gitignore` file,
preventing it from being tracked and committed to the repository.

So just specify the environment variables that will contain the values of your secrets.
For example, if you have a secret named `API_KEY`,
create an environment variable named `API_KEY` and set the value of the corresponding secret for it

Now navigate to **Dashboard**, select your instance of *Web Service* and select the **Environment** tab in the sidebar.

Here you need to pass only one variable - `APP_ENV`.
Make sure that your web application has up-to-date environment data in the repository.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-web-env.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c97994474cf6b489b0b1f492539b3d92" alt="Configuration Web Environments" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/render-web-env.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-web-env.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8437fd27f18bd0dd15d3c1989c683d13 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-web-env.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5b30e0e8833c3570c69fb6b7e1215539 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-web-env.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=fd75d0447421f034d755558806bf792a 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-web-env.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=943a0d9201fbe745e706e8e51541f8c4 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-web-env.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ebb6b2214969e049f0eb2c936348e10e 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-web-env.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=73584cdf04a8c8437bb29e91db4c7c05 2500w" />

In the same way, specify the necessary environments in the *API Service* instance.

## Cloudflare

<Note>
  Render provides an initial URL of the form `*.onrender.com` to all deployed services.
  `onrender.com` is a [public suffix domain](https://publicsuffix.org/) as it’s a shared domain across
  all Render services - and is done so in order to protect users from being able to read each other’s cookies.

  Ship uses cookies to store tokens on the front-end side.
  Therefore, you need a different domain to successfully deploy the application.

  If you don't have a personal domain, you can use free solutions for educational purposes, such as
  [free-domain](https://github.com/Olivr/free-domain) repository.
</Note>

Navigate to your Render application and open the `Settings` tab,
scroll down to the `Custom Domains` section and click the `Add Custom Domain` button.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=835854e210bf768ad9b318c301dfa5ab" alt="Render Custom Domains" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/render-custom-domains.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=dc50fd453e9dfbb52fd0cd5c1f611d4e 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d3a23a3ce719f85d2d59577e766c8bf8 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=3b5713b358cf9d72c968d1a6aaae3a08 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=545acd9bd64775ae24364d9018e2930c 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=0945acd75f984873d6504a8477b55410 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=bfe3facc13099254d4716e2ea74b85ef 2500w" />

Type your desired domain and click the `Save` button.

After adding a new custom domain, you need to add a `CNAME` record in your DNS provider.
Copy this alias for your app and move on.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains-created.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e6e21b8c9f73974691980e840f035420" alt="Render new domain" data-og-width="1512" width="1512" data-og-height="945" height="945" data-path="images/render-custom-domains-created.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains-created.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=8138fcaa5805669c43e4e578f893598d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains-created.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=701fdc5b5f60642ddbeccc897ed0ba24 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains-created.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a4ab21f4837f63cd99a006910ba31e72 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains-created.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=69f2e7e5a28aacc8960a5a23f025b65c 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains-created.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=46af59b6fc858dbed585a28832cf58eb 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/render-custom-domains-created.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=392435bb23b4730b2cbc3d38bb4cc0dc 2500w" />

Navigate to [CloudFlare](https://dash.cloudflare.com/) and sign in to account.

1. Go to `DNS` tab and create a new record.
2. Click `Add record`. Select type `CNAME`,
   enter domain name (must be the same you entered in Render settings) and paste alias into `target` field.
   Make sure `Proxy status` toggle enabled.
3. Save changes

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns-render.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=ab4bfb23db33ef403a27916b6c536a8a" alt="Cloudflare DNS" data-og-width="1143" width="1143" data-og-height="614" height="614" data-path="images/cloudflare-create-dns-render.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns-render.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=cbdd8ab9b8ecca6cc0095ebc64b2ca58 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns-render.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=c64f761d444042cf2c9bfda20a8e8738 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns-render.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f52ad6cb247d308357093d7dd41acde6 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns-render.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=2b1508100e63d7c076f3e6f36690f44e 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns-render.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=6692cea1cee4bc408ac249958b43272f 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cloudflare-create-dns-render.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=686a5738d512f6efcdab5ff3ba5b1e81 2500w" />

Now go back to Custom Domains Settings and click the `Verify` button.
It usually takes about 5 minutes for Render to confirm your domain and issue a certificate and start using your new domain.
Once the domain is confirmed, application can be accessed by new address.

Now make sure you have up-to-date environments in your API and Web applications.


# How it Works
Source: https://ship.paralect.com/docs/examples/api-public-docs/how-it-works



When you're calling `registerDocs` function, we add config in Registry. You can register docs in any part of application.
This config is written with this [standard](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject) in mind.
This registry contains all actions that gathered inside API. To retrieve these docs in open api format, you can call `docsService.getDocs` function.

For advanced usage cases, you can reference to this [documentation](https://github.com/asteasolutions/zod-to-openapi)


# Overview
Source: https://ship.paralect.com/docs/examples/api-public-docs/overview



Keeping your public API up to date can be a cumbersome task that requires manually updating files. Our solution eliminates this hassle by allowing you to document your code itself, so you can focus on development without worrying about API updates.

The example demonstrates how to add Api public docs and the components included in the Ship to build a web application that supports documentation of API with Open API specification.
The example includes documentation and sample code that will help the developer in the process of integrating with the Ship template.

[Example with code](https://github.com/paralect/ship/tree/main/examples/public-docs)


# Usage
Source: https://ship.paralect.com/docs/examples/api-public-docs/usage



Just add `docsService.registerDocs` in your code. For example

```typescript  theme={null}
// resources/account/actions/sign-up/doc.ts
const config: RouteExtendedConfig = {
  private: false,
  tags: [resourceName],
  method: 'post',
  path: `/${resourceName}/sign-up`,
  summary: 'Sign up',
  request: {},
  responses: {},
};
export default config;

// resources/account/actions/sign-up/index.ts
import docConfig from './doc';

export default (router: AppRouter) => {
  docsService.registerDocs(docConfig);

  router.post('/sign-up', validateMiddleware(schema), validator, handler);
};
```

Here we just added `/account/sign-up` path to open api specification. Later on we will learn how to customise it.
To look at result you can launch application and make call to api endpoint with `/docs/json` path. E.g. `http://localhost:3002/docs/json` if you're using local server.
It will return you json specification in [Open API standard](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#serverObject).
You can use tools like [Swagger Editor](https://editor-next.swagger.io/) to see it in pretty editor.

In order to add body, params or query, you can add zod schema inside `request` property.
E.g. for body it will look like that:

```typescript  theme={null}
// schemas/empty.schema.ts
export const EmptySchema = docsService.registerSchema('EmptyObject', z.object({}));

// resources/account/actions/sign-up/schema.ts
export const schema = z.object({
  firstName: z.string().min(1, 'Please enter First name').max(100),
  lastName: z.string().min(1, 'Please enter Last name').max(100),
  email: z.string().min(1, 'Please enter email').email('Email format is incorrect.'),
  password: z.string().regex(
    PASSWORD_REGEXP,
    'The password must contain 6 or more characters with at least one letter (a-z) and one number (0-9).',
  ),
});

// resources/account/actions/sign-up/doc.ts
import { resourceName } from 'resources/account/constants';
import { schema } from './schema';
import { EmptySchema } from 'schemas/empty.schema';

const config: RouteExtendedConfig = {
  private: false,
  tags: [resourceName],
  method: 'post',
  path: `/${resourceName}/sign-up`,
  summary: 'Sign up',
  request: {
    body: { content: { 'application/json': { schema } } },
  },
  responses: {
    200: {
      description: 'Empty data.',
      content: {
        'application/json': {
          schema: EmptySchema,
        },
      },
    },
  },
};

export default config;
```

Here we also added details inside `responses` property to let api user know what we might expect from there. For that we have used `docsService.registerSchema` function. For more details you can look at this [documentation](https://github.com/asteasolutions/zod-to-openapi)

For query, it will look like that:

```typescript  theme={null}
// resources/account/actions/verify-email/schema.ts
export const schema = z.object({
  token: z.string().min(1, 'Token is required'),
});

// resources/account/actions/verify-email/doc.ts
import { resourceName } from 'resources/account/constants';
import { schema } from './schema';

const config: RouteExtendedConfig = {
  private: false,
  tags: [resourceName],
  method: 'get',
  path: `/${resourceName}/verify-email`,
  summary: 'Verify email',
  request: {
    query: schema,
  },
  responses: {
    302: {
      description: 'Redirect to web app',
    },
  },
};

export default config;
```

Also, there is an option to make the endpoint secure. Just set the `private` property to `true`, and it will add JWT authorization to this endpoint.
If your auth method is not JWT, then there is built-in `cookie-auth` strategy. To update set it, you can set `authType` in config.

```typescript  theme={null}
// resources/account/actions/verify-email/doc.ts
import { resourceName } from 'resources/account/constants';
import { schema } from './schema';

const config: RouteExtendedConfig = {
  private: false,
  authType: 'cookieAuth',
  tags: [resourceName],
  method: 'get',
  path: `/${resourceName}/verify-email`,
  summary: 'Verify email',
  request: {
    query: schema,
  },
  responses: {
    302: {
      description: 'Redirect to web app',
    },
  },
};

export default config;
```

If you need other strategies, please look at `docs.service.ts` file. There will be option to extend methods like that:

```typescript  theme={null}
registry.registerComponent('securitySchemes', 'customAuth', {
  type: 'apiKey',
  in: 'cookie',
  name: 'JSESSIONID',
});
```


# Overview
Source: https://ship.paralect.com/docs/examples/overview



<Info>
  It's the draft version of **Examples** documentation, the articles contains some deprecated details. This section will be refactored and actualized soon ✨.
</Info>

The example section in the Ship documentation provides developers with a set of working examples that demonstrate how to use the various services and components that are included in the Ship.
The examples are designed to help developers get up and running with the boilerplate quickly and efficiently!

## List of examples

* **[Stripe Subscriptions](/examples/stripe-subscriptions/overview)**
* **[Public Docs](/examples/api-public-docs/overview)**


# Stripe account
Source: https://ship.paralect.com/docs/examples/stripe-subscriptions/account



## Api keys

Navigate to the `Developers` tab [link](https://dashboard.stripe.com/test/developers) and select `API keys` in the left sidebar.
Here you can find two keys - public and secret.

Public key is required by the client-side stripe library (for example - a payment form to purchase a product or add a card for later use).
(Ship uses client-side stripe library to display add card form)

Secret key is used to interract with stripe using application's server.

Copy them and store in web's (public key) configs and server's configs (secret key)

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-api-keys.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=30870fc1a0cbe325eebd818b5d6b00c7" alt="Stripe create product form" data-og-width="1585" width="1585" data-og-height="584" height="584" data-path="images/web/stripe/stripe-api-keys.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-api-keys.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=1ccc4be15c892c8be2b8e647504cc878 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-api-keys.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=2f11a647f7a56a555da623c5a7f2fc76 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-api-keys.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6e1c07a0a3f0f712c856bf54f6c645b6 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-api-keys.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=6041f0651f47abf081d4c32f13a4e46b 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-api-keys.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5be3230e0be199accc1c1e0e5099b55c 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-api-keys.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b660c16602423d0d24ff1815d1be33a8 2500w" />

## Webhooks

Webhooks allow stripe to communicate with your server by sending plain POST requests on every event, that happens on stripe. During adding a new webhook you can select which events should be sent to the server.

Start creating a new webhook by clicking on the `+ Add endpoint` button.
Type URL of the endpoint, responsible for listening for the stripe events (Default ship URL is `HTTPS://<server_url>/webhook/stripe`).
Add events that you want to listen to. Ship listens for the following events -

* `setup_intent.succeeded`
  Triggers when a customer adds a new card using stripe form on the web application.
* `customer.subscription.create`
  Triggers when a customer's subscription created
* `payment_method.attached`
  Triggers when a customer adds a new card during the payment process on stripe checkout page
* `customer.subscription.updated`
  Triggers when a customer's subscription changes
* `customer.subscription.deleted`
  Triggers when a customer's subscription is deleted.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-create.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b9545b8ce73a4c94a793771b89279389" alt="Stripe create webhook form" data-og-width="861" width="861" data-og-height="768" height="768" data-path="images/web/stripe/stripe-webhook-create.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-create.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a7a7a0f89154fcb673d9db9bfda89a7d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-create.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b2ca81146e08e2fa2f086c916c28bd1a 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-create.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=da0a2bdc146154d16a76734f2d7a7f6b 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-create.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f0bbefcd655c534a5c4154eb4ce7c879 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-create.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5f8af2455db4db51e6cdb6dbb27f88b1 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-create.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7542c3a10e0a26eba87107c026f7009c 2500w" />

Navigate to the created webhook and reveal webhook secret. Copy this value to API config's

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-key.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=dd2eafd7ca86c9358618dbfef9be8142" alt="Stripe webhook details page" data-og-width="827" width="827" data-og-height="252" height="252" data-path="images/web/stripe/stripe-webhook-key.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-key.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=7fda686b124cb07e00252b5a24e6d9e4 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-key.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=e042f5ba53bf5a692171a834c6bcbe2f 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-key.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=86e2bab19a478909a7659967939fec7c 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-key.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a54fc3e2a875b77a4c0ac2e0fcaae321 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-key.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=040312b7472c610894668f263e369aeb 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-webhook-key.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a8137adec9efc2d9d6acfd5f34730218 2500w" />

For local development, you can use Stripe CLI to forward events on your localhost - [link](https://stripe.com/docs/stripe-cli)

## Subscription products

Navigate to the product tab [link](https://dashboard.stripe.com/test/products) and press the Button `+ Add product` in the top right corner.

Add product name and, optionally, description and image.
Next, add price information. To create a basic subscription with recurring payments, select pricing model `Standard pricing`, add price and currency, select `Recurring` option below the price, and select Billing period.

Stripe allows to setup several prices for product. Ship uses subscripti ons with two payment periods - monthly and yearly, therefore stripe product should has two prices. Click the button `+ Add another price` at the bottom and fill in the second form. Make sure prices have `Monthly` and `Yearly` billing periods

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-create.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=22fff3df360d84d94e09eea42a1af41a" alt="Stripe create product form" data-og-width="649" width="649" data-og-height="1160" height="1160" data-path="images/web/stripe/stripe-product-create.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-create.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ba1bdcc8a3c63ea9d9a8b361c6843cf9 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-create.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f4d312f429e98ac8b883d8c2f27028f3 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-create.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c07abbd43b82fe643d0d1afe3f604e49 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-create.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=b779ffedb103548bcf47e41ff870bb69 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-create.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=83073432bf506fe3cc008673afc32c70 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-create.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=0136b6305870f54339cdc818d217571b 2500w" />

Open created product detailed view. Here you can find information about prices, logs and events, related to this product.
Purchase operation requires price ids of the product. Copy them and store them in the application's config

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-details.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=0bb104e6ae3ff74f4fab80b9004eb65e" alt="Stripe product details page" data-og-width="1586" width="1586" data-og-height="1024" height="1024" data-path="images/web/stripe/stripe-product-details.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-details.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=4460dec4802ea6da50ae0a8640e22498 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-details.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=d8507548f48e73821098fd7dea55a38c 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-details.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=83cb61a7e7a2227eeb95dc1872da9bea 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-details.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=18f7e60f5640f2ff075e6bb7debd8e13 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-details.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=12e548e7158f66ade477a400a7c38e15 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/web/stripe/stripe-product-details.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cbfdea9b19a66965f765f5499af8a0b2 2500w" />


# Overview
Source: https://ship.paralect.com/docs/examples/stripe-subscriptions/api/overview



This section contains list of stripe api calls, used in the application with brief description of each.


# Payments
Source: https://ship.paralect.com/docs/examples/stripe-subscriptions/api/payments



## POST /payments/create-setup-intent

Generates a one-time secret key to allow the web application to communicate with stripe directly

Returns `clientSecret` token, used by `@stripe/react-stripe-js` components.

Stripe call snippet -

```typescript  theme={null}
const setupIntent = await stripeService.setupIntents.create({
    customer: user.stripeId,
    payment_method_types: ['card'],
});
```

Parameters description -

| Parameter              | type   | Description                                                                 |
| ---------------------- | ------ | --------------------------------------------------------------------------- |
| customer               | string | id of the stripe customer                                                   |
| payment\_method\_types | array  | The list of payment method types that this SetupIntent is allowed to set up |

More information about stripe `SetupIntent` object - [link](https://stripe.com/docs/api/setup_intents/object)

## GET /payments/payment-information

Returns customer's billing details, balance on stripe account and card information (last 4 digits, expiration date and brand)

Stripe call snippet -

```typescript  theme={null}
const paymentInformation = await stripeService.customers.retrieve(user.stripeId, {
    expand: ['invoice_settings.default_payment_method'],
});
```

Parameters description -

| Parameter | type   | Description                                                                                                                                                                   |
| --------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| stripeId  | string | id of the stripe customer                                                                                                                                                     |
| expand    | array  | By default, stripe returns only the if of the related object (default\_payment\_method in this case). Those objects can be expanded inline with the expand request parameter. |

More information about stripe `Customer` object - [link](https://stripe.com/docs/api/customers/object)

## GET /payments/get-history

Returns a list of the customer's charges. The charges are returned in sorted order, with the most recent charges appearing first.

Query params -

| Parameter | type   | Description                                                                                                                                                                                                                                                                                         |
| --------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| cursorId  | string | A cursor for use in pagination. starting\_after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj\_foo, your subsequent call can include starting\_after=obj\_foo in order to fetch the next page of the list. |
| direction | string | A direction of pagination. Used to determine which parameter `starting_after` or `ending_before` should be passed to the stripe call                                                                                                                                                                |
| perPage   | string | A limit on the number of objects to be returned                                                                                                                                                                                                                                                     |

Stripe call snippet -

```typescript  theme={null}
const charges = await stripeService.charges.list({
    limit: perPage,
    customer: user.stripeId as string,
    starting_after: cursorId,
});
```

More information about stripe `Charge` object - [link](https://stripe.com/docs/api/charges/object)

More information about stripe pagination - [link](https://stripe.com/docs/api/pagination)


# Subscriptions
Source: https://ship.paralect.com/docs/examples/stripe-subscriptions/api/subscriptions



## POST /subscriptions/subscribe

Generates subscription for customer and returns a link to checkout session where user can review payment details, provides payment information, and purchase a subscription.

Body params -

| Parameter | type   | Description                      |
| --------- | ------ | -------------------------------- |
| priceId   | string | Id of the price for subscription |

Returns `checkoutLink` url with checkout form.

Stripe call snippet -

```typescript  theme={null}
  const session = await stripeService.checkout.sessions.create({
    mode: 'subscription',
    customer: user.stripeId,
    line_items: [{
      quantity: 1,
      price: priceId,
    }],
    success_url: `${config.webUrl}?subscriptionPlan=${priceId}`,
    cancel_url: config.WEB_URL,
  });
```

Parameters description -

| Parameter                                | type                                    | Description                                                                                                               |
| ---------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| mode                                     | string                                  | The mode of the Checkout Session. For subscription it should be set to `subscription`                                     |
| customer                                 | string                                  | id of the stripe customer. if `undefined`, stripe will ask for the user's email and create a new customer upon purchasing |
| line\_items                              | array                                   | Array with information about items that will be included in checkout session                                              |
| <ul><li>quantity</li><li>price</li></ul> | <ul><li>number</li><li>string</li></ul> | <ul><li>Amount of items (usually 1 for subscription)</li><li>id of the specific price of the product</li></ul>            |
| success\_url                             | string                                  | The URL to which Stripe should send customers when payment or setup is complete                                           |
| cancel\_url                              | string                                  | The URL the customer will be directed to if they decide to cancel payment and return to your website                      |

More information about stripe checkout object - [link](https://stripe.com/docs/api/checkout/sessions)

## POST /subscriptions/cancel-subscription

Cancels prolongation of a customer’s subscription. The customer will not be charged again for the subscription.

Stripe call snippet -

```typescript  theme={null}
  stripeService.subscriptions.update(user.subscription?.subscriptionId as string, {
      cancel_at_period_end: true,
  });
```

Parameters description -

| Parameter               | type    | Description                                                                          |
| ----------------------- | ------- | ------------------------------------------------------------------------------------ |
| customer                | string  | id of the stripe customer                                                            |
| cancel\_at\_period\_end | boolean | Indicating whether this subscription should cancel at the end of the current period. |

More information about subscription update - [link](https://stripe.com/docs/api/subscriptions/update)

## POST /subscriptions/upgrade

Changes customer's subscription plan (billing period or subscription plan)

Body params -

| Parameter | type   | Description                      |
| --------- | ------ | -------------------------------- |
| priceId   | string | Id of the price for subscription |

Stripe call snippet -

```typescript  theme={null}
  const subscriptionDetails = await stripeService.subscriptions.retrieve(subscriptionId);

  const items = [{
    id: subscriptionDetails.items.data[0].id,
    price: priceId,
  }];

  await stripeService.subscriptions.update(subscriptionId, {
    proration_behavior: 'always_invoice',
    cancel_at_period_end: false,
    items,
  });
```

Parameters description -

| Parameter                          | type                                    | Description                                                                                                                                                             |
| ---------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| subscriptionId                     | string                                  | id of the customer's active subscription                                                                                                                                |
| proration\_behavior                | string                                  | Determines how to handle prorations when the billing cycle changes (switching plan in this case). parameter `Always_invoice` is used to charge the customer immediately |
| cancel\_at\_period\_end            | string                                  | Boolean indicating whether this subscription should cancel at the end of the current period.                                                                            |
| items                              | array                                   | array with information about subscription items                                                                                                                         |
| <ul><li>id</li><li>price</li></ul> | <ul><li>string</li><li>string</li></ul> | <ul><li>id of the customer's active subscription</li><li>id of the specific price of the product</li></ul>                                                              |

More information about subscription update - [link](https://stripe.com/docs/api/subscriptions/update)

## GET /subscriptions/current

Returns detailes subscription information along with pending invoice

Stripe call snippet -

```typescript  theme={null}
  const product = await stripeService.products.retrieve(user.subscription?.productId);
```

| Parameter | type   | Description                      |
| --------- | ------ | -------------------------------- |
| productId | string | id of the product (subscription) |

More information about products - [link](https://stripe.com/docs/api/products)

```typescript  theme={null}
  const pendingInvoice = await stripeService.invoices.retrieveUpcoming({
    subscription: user.subscription?.subscriptionId,
  });
```

| Parameter    | type   | Description                              |
| ------------ | ------ | ---------------------------------------- |
| subscription | string | id of the customer's active subscription |

More information about invoices - [link](https://stripe.com/docs/api/invoices)

## GET /subscriptions/preview-upgrade

Returns invoice with billing information of subscription upgrade/downgrade

Query params -

| Parameter | type   | Description                      |
| --------- | ------ | -------------------------------- |
| priceId   | string | Id of the price for subscription |

Returns invoice with payment details

Code snippet -

```typescript  theme={null}
  if (priceId === 'price_0') {
    items = [{
      id: subscriptionDetails.items.data[0].id,
      price_data: {
        currency: 'USD',
        product: user.subscription?.productId,
        recurring: {
          interval: subscriptionDetails.items.data[0].price.recurring?.interval,
          interval_count: 1,
        },
        unit_amount: 0,
      },
    }];
  } else {
    items = [{
      id: subscriptionDetails.items.data[0].id,
      price: priceId,
    }];
  }

  const invoice = await stripeService.invoices.retrieveUpcoming({
    customer: user.stripeId || undefined,
    subscription: user.subscription?.subscriptionId,
    subscription_items: items,
    subscription_proration_behavior: 'always_invoice',
  });
```

Parameters description -

| Parameter                          | type                                    | Description                                                                                                                                                                                   |
| ---------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| customer                           | string                                  | id of the stripe customer                                                                                                                                                                     |
| subscription                       | string                                  | id of customer's active subscription                                                                                                                                                          |
| subscription\_proration\_behavior  | string                                  | Determines how to handle prorations when the billing cycle changes (e.g., when switching plans, resetting billing\_cycle\_anchor=now, or starting a trial), or if an item’s quantity changes. |
| subscription\_items                | array                                   | array with information about subscription items                                                                                                                                               |
| <ul><li>id</li><li>price</li></ul> | <ul><li>string</li><li>string</li></ul> | <ul><li>id of the customer's active subscription</li><li>id of the specific price of the product</li></ul>                                                                                    |

In case the customer chooses free plan, we need to send a custom price object to stripe with unit\_amount set to 0 in order to receive invoice with empty products and information about a refund for canceled subscription

Price data parameters -

| Parameter                                          | type                                    | Description                                                                                                                                   |
| -------------------------------------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| currency                                           | string                                  | Three-letter ISO currency code, in lowercase.                                                                                                 |
| product                                            | string                                  | id of subscription product                                                                                                                    |
| recurring                                          | object                                  | The recurring components of a price such as interval and interval\_count                                                                      |
| <ul><li>interval</li><li>interval\_count</li></ul> | <ul><li>string</li><li>number</li></ul> | <ul><li>Specifies billing frequency. Either day, week, month or year.</li><li>The number of intervals between subscription billings</li></ul> |
| unit\_amount                                       | number                                  | A positive integer in cents (or 0 for a free price) representing how much to charge.                                                          |

More information about previewing upcoming invoices - [link](https://stripe.com/docs/api/invoices/upcoming)


# Overview
Source: https://ship.paralect.com/docs/examples/stripe-subscriptions/overview



The example demonstrates how to use the Stripe API and the components included in the Ship to build a web application that supports subscription-based billing.
The example includes documentation and sample code that will help the developer in the process of integrating Stripe subscriptions with the Ship template.

[Example with code](https://github.com/paralect/ship/tree/main/examples/stripe-subscriptions)


# Git Hooks
Source: https://ship.paralect.com/docs/git-hooks

Automated code quality checks with Husky and lint-staged

Ship uses [Husky](https://typicode.github.io/husky/) and [lint-staged](https://github.com/lint-staged/lint-staged) to automatically validate and auto-fix the entire project before each commit, ensuring consistent code quality across the codebase.

## How It Works

When you commit changes, Husky triggers a pre-commit hook that runs lint-staged. The configuration runs linters on the **entire project** to ensure project-wide code quality.

<Info>
  The pre-commit hook is automatically installed when you run `pnpm install` via the `prepare` script.
</Info>

<Note>
  **Project-wide Validation**: Ship intentionally runs linters on ALL project files (using `.`), not just staged files. This defensive approach ensures that if someone bypassed hooks with `--no-verify`, the next commit will auto-fix those issues and prevent blocking other team members.
</Note>

## Configuration

### API

<CodeGroup>
  ```json TypeScript Files theme={null}
  "lint-staged": {
    "*.ts": [
      "eslint . --fix",
      "bash -c 'tsc --noEmit'",
      "prettier . --write"
    ]
  }
  ```

  ```json JSON & Markdown theme={null}
  "lint-staged": {
    "*.{json,md}": [
      "prettier . --write"
    ]
  }
  ```
</CodeGroup>

When any `.ts` file is staged, runs on **entire project**:

1. **ESLint** - Auto-fixes all `.ts` files (note the `.`)
2. **TypeScript** - Type checks all files
3. **Prettier** - Formats all files (note the `.`)

### Web

<CodeGroup>
  ```json TypeScript/React Files theme={null}
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint . --fix",
      "bash -c 'tsc --noEmit'",
      "prettier . --write"
    ]
  }
  ```

  ```json CSS Files theme={null}
  "lint-staged": {
    "*.css": [
      "stylelint . --fix",
      "prettier . --write"
    ]
  }
  ```

  ```json JSON & Markdown theme={null}
  "lint-staged": {
    "*.{json,md}": [
      "prettier . --write"
    ]
  }
  ```
</CodeGroup>

### Packages

All shared packages (`schemas`, `mailer`, `app-types`, etc.) have similar lint-staged configurations tailored to their file types.

## Customization

### Modify Linters

Edit `lint-staged` in your `package.json`:

```json  theme={null}
"lint-staged": {
  "*.ts": [
    "eslint . --fix",       // The '.' runs on entire project
    "prettier . --write"    // The '.' formats all files
    // Add or remove tools as needed
  ]
}
```

### Run on Staged Files Only (Alternative)

If you prefer to only lint staged files instead of the entire project:

```json  theme={null}
"lint-staged": {
  "*.ts": [
    "eslint --fix",         // No '.' - only staged files
    "prettier --write"      // No '.' - only staged files
  ]
}
```

<Warning>
  Linting only staged files means errors in other parts of the codebase (e.g., from `--no-verify` commits) won't be caught or fixed until those files are modified.
</Warning>

### Skip Hooks Temporarily

```bash  theme={null}
# Bypass pre-commit hook (not recommended)
git commit --no-verify -m "message"
```

<Tip>
  Only skip hooks when absolutely necessary, as they help maintain code quality.
</Tip>

## Troubleshooting

### Hook Not Running

If pre-commit hooks don't run:

1. Ensure Husky is installed:

```bash  theme={null}
pnpm install
```

2. Check if `.husky/pre-commit` exists in your project root

3. Verify Git hooks path:

```bash  theme={null}
git config core.hooksPath
```

### Linter Errors Blocking Commits

If linters fail:

1. Review the error output
2. Fix the issues manually or let auto-fix handle them
3. Stage the fixed files: `git add .`
4. Commit again

## Best Practices

* **Never use `--no-verify`** - It bypasses quality checks and can break the build for teammates
* **Fix issues early** - Don't accumulate linting errors across the codebase
* **Keep configs in sync** - Ensure lint-staged matches your editor settings


# GitHub Actions
Source: https://ship.paralect.com/docs/github-actions

Pre-configured CI/CD workflows for automated building and linting

Ship includes GitHub Actions workflows in `.github/workflows/` that run automatically on pull requests to validate builds and enforce code quality.

## Workflows Overview

<CardGroup cols={2}>
  <Card title="Build Workflows" icon="docker" iconType="duotone">
    Validate Docker builds for API and Web
  </Card>

  <Card title="Lint Workflows" icon="broom" iconType="duotone">
    Run ESLint, TypeScript, and Prettier
  </Card>
</CardGroup>

## Build Workflows

Workflows build Docker images to ensure they compile successfully before merging. They use BuildKit caching to speed up builds.

### Build API

**File**: `.github/workflows/build-api.yml`

**Triggers**: PRs to `main` with changes in `apps/api/**` or `packages/**`

<CodeGroup>
  ```yaml Key Configuration theme={null}
  on:
    pull_request:
      branches: [main]
      paths:
        - apps/api/**
        - packages/**

  jobs:
    build:
      steps:
        - uses: docker/build-push-action@v5
          with:
            file: ./apps/api/Dockerfile
            push: false
            cache-from: type=local,src=/tmp/.buildx-cache
  ```
</CodeGroup>

### Build Web

**File**: `.github/workflows/build-web.yml`

**Triggers**: PRs to `main` with changes in `apps/web/**` or `packages/**`

<CodeGroup>
  ```yaml Key Configuration theme={null}
  on:
    pull_request:
      branches: [main]
      paths:
        - apps/web/**
        - packages/**

  jobs:
    build:
      steps:
        - uses: docker/build-push-action@v5
          with:
            file: ./apps/web/Dockerfile
            push: false
            cache-from: type=local,src=/tmp/.buildx-cache
  ```
</CodeGroup>

## Lint Workflows

Linting uses a reusable template workflow that runs ESLint, TypeScript, and Prettier checks.

### Linter Template

**File**: `.github/workflows/linter.template.yml`

Reusable workflow for running linters with pnpm and Node.js.

<CodeGroup>
  ```yaml Environment theme={null}
  env:
    PNPM_VERSION: 9.5.0
    NODE_VERSION: 22.13.0
  ```

  ```yaml Linters theme={null}
  - name: Run Linters
    uses: wearerequired/lint-action@v2
    with:
      eslint: true
      eslint_dir: ${{ inputs.dir }}
      tsc: true
      tsc_dir: ${{ inputs.dir }}
      prettier: true
      prettier_dir: ${{ inputs.dir }}
  ```
</CodeGroup>

<Info>
  The [lint-action](https://github.com/wearerequired/lint-action) automatically posts inline comments on PRs for linting issues.
</Info>

### Lint API & Web

**Files**: `.github/workflows/run-api-linter.yml`, `.github/workflows/run-web-linter.yml`

**Triggers**: PRs to `main` with changes in respective apps or packages

<CodeGroup>
  ```yaml API theme={null}
  jobs:
    lint:
      uses: ./.github/workflows/linter.template.yml
      with:
        component: api
        dir: apps/api
  ```

  ```yaml Web theme={null}
  jobs:
    lint:
      uses: ./.github/workflows/linter.template.yml
      with:
        component: web
        dir: apps/web
  ```
</CodeGroup>

## Customization

### Update Node.js/pnpm Versions

Edit `.github/workflows/linter.template.yml`:

```yaml  theme={null}
env:
  PNPM_VERSION: 9.5.0    # Update version
  NODE_VERSION: 22.13.0  # Update version
```

<Tip>
  All workflows support manual triggering via `workflow_dispatch` for testing.
</Tip>


# Introduction
Source: https://ship.paralect.com/docs/introduction



<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/ship.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=c7955fe05812f01991eed85354fc6da0" alt="" data-og-width="7840" width="7840" data-og-height="3200" height="3200" data-path="images/ship.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/ship.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=42e75c88f9a95f20b60373c6b35c8190 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/ship.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=0253c9340f50c4532f7de66263fe245d 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/ship.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=de8c4d621e65ff3df1db49371d144556 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/ship.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=31ec610fd140d747952d8cb9fb8e5bf4 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/ship.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=da21354ec851968074b76dc2a2b3a360 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/ship.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=2f3a370b34fc86a59dc48b0ff0a5428e 2500w" />

The [Ship](https://ship.paralect.com/) is a Full-Stack Node.js boilerplate that will help you build and launch products faster. You can focus on getting things done, not building infrastructure.

Ship uses simple tools and approaches and has built-in support for everything from the frontend to CI/CD automation. The Ship was first created in 2015 and since then we keep testing it on real products at [Paralect](https://www.paralect.com/).

## Key principles

### 😊 Simplicity

We use the most simple solutions in every part of the Ship. They are easier to understand, test, and maintain.

### 📈 Product comes first

Our jobs from engineer to CEO only exist because there are customers who use the products we create. We encourage developers to focus on a product more than on technology. Get things done as quickly as possible with the Ship.

### 🚀 Production ready

You can use Ship to create production-ready products. We prefer to use well-tested technologies.

### 🥷 For developers

Ship is written for developers and easy to use and understand. We write documentation to explain how things work.

## Getting started

The best way to get started with Ship is to use [Ship CLI](/packages/create-ship-app) to bootstrap your project.

```
npx create-ship-app@latest init
```

This command will create everything you need to develop, launch locally and deploy your product.

## Next steps

### Launch your project

We use [Turborepo](https://turborepo.org/docs) for managing monorepo. To run infra and all services -- just run: `npm start` 🚀

### Learn key concepts

Learn about Ship [architecture](/architecture) and key components([Web](/web/overview), [API](/api-reference/overview), [Deployment](/deployment/digital-ocean-apps), [Migrator](/migrator), [Scheduler](/scheduler).


# LLMs.txt
Source: https://ship.paralect.com/docs/llms



Ship provides LLM-friendly documentation following the [llmstxt.org standard](https://llmstxt.org/), automatically generated by [Mintlify](https://mintlify.com/docs/ai/llmstxt).

## Available Files

### llms.txt

A structured list of all documentation pages with links and descriptions. Similar to how a sitemap helps search engines, this file helps AI tools understand your documentation structure.

* **View**: [/llms.txt](/llms.txt)
* **URL**: `https://ship.paralect.com/docs/llms.txt`

### llms-full.txt

The complete documentation site combined into a single file for full context.

* **View**: [/llms-full.txt](/llms-full.txt)
* **URL**: `https://ship.paralect.com/docs/llms-full.txt`

## Key Differences

| Feature      | llms.txt                     | llms-full.txt               |
| ------------ | ---------------------------- | --------------------------- |
| **Content**  | Page links with descriptions | Complete documentation text |
| **Size**     | Lightweight                  | Comprehensive               |
| **Best for** | Quick navigation             | Full context                |

**Use `llms.txt`** when AI tools can fetch pages as needed (ChatGPT, Claude).\
**Use `llms-full.txt`** when you need all context upfront (Cursor).

## Usage with AI Tools

### Cursor

Use the `@Docs` feature:

1. Type `@Docs` in your prompt
2. Reference: `https://ship.paralect.com/docs/llms-full.txt`
3. Ask questions about Ship

### ChatGPT & Claude

1. Mention you're using Ship framework
2. Reference: `https://ship.paralect.com/docs/llms.txt`
3. The AI will fetch the documentation

## Example Prompts

* "Using Ship framework, how do I create a new API endpoint with validation?"
* "Show me how to set up event handlers in Ship"
* "How to deploy Ship to Digital Ocean?"

## Learn More

* [llmstxt.org standard](https://llmstxt.org/)
* [Mintlify llms.txt documentation](https://mintlify.com/docs/ai/llmstxt)


# Mailer
Source: https://ship.paralect.com/docs/mailer



### Overview

The **Mailer** package is a utility designed to facilitate the process of generating email templates. This package provides a way to style, template, and generate HTML for sending emails using the [`React Email`](https://react.email/) library

### Template System

The template system is key to the functionality of the **Mailer** package. Each template corresponds to a different type of email that can be sent. The specific variables available for substitution in a template depend on the template itself.

The Template type should be used to reference the available templates.  For example, to reference to verify email template, you would use `Template.VERIFY_EMAIL`.

## Adding new Template

All development takes place in the package turborepo `packages/mailer`. The preview of emails is launched automatically when you launch the application using turborepo or Docker, the application will be available on port 4000.

1. Create a new template in the `emails` folder.
2. Export your component and props interface from the file.

```typescript my-app/packages/mailer/emails/verify-email.tsx theme={null}
import React, { FC } from 'react';
import { Text } from '@react-email/components';

import Layout from './_layout';
import Button from './components/button';

export interface VerifyEmailProps {
  firstName: string;
  href: string;
}

export const VerifyEmail:FC<VerifyEmailProps> = ({
  firstName = 'John',
  href = 'https://ship.paralect.com',
}) => (
  <Layout previewText="Welcome on board the Ship!">
    <Text>
      Dear
      {' '}
      {firstName}
      ,
    </Text>

    <Text>
      Welcome to Ship! We are excited to have you on board.
    </Text>

    <Text>
      Before we get started, we just need to verify your email address.
      This is to ensure that you have access to all our features and so we can send you important account notifications.
    </Text>

    <Text>
      Please verify your account by clicking the button below:
    </Text>

    <Button href={href}>
      Verify email
    </Button>
  </Layout>
);

export default VerifyEmail;
```

3. Navigate to `src/template.ts` file, import your component and props interface.
4. Add your template to the `Template` enum, `EmailComponent` object and `TemplateProps` type.

```typescript my-app/packages/mailer/src/template.ts theme={null}
import { ResetPassword, ResetPasswordProps } from 'emails/reset-password';
import { SignUpWelcome, SignUpWelcomeProps } from 'emails/sign-up-welcome';
import { VerifyEmail, VerifyEmailProps } from 'emails/verify-email';

export enum Template {
  RESET_PASSWORD,
  SIGN_UP_WELCOME,
  VERIFY_EMAIL,
}

export const EmailComponent = {
  [Template.RESET_PASSWORD]: ResetPassword,
  [Template.SIGN_UP_WELCOME]: SignUpWelcome,
  [Template.VERIFY_EMAIL]: VerifyEmail,
};

export type TemplateProps = {
  [Template.RESET_PASSWORD]: ResetPasswordProps;
  [Template.SIGN_UP_WELCOME]: SignUpWelcomeProps;
  [Template.VERIFY_EMAIL]: VerifyEmailProps;
};

```

<Tip>
  When you change the email template, you need to rebuild the API to see the changes when sending emails.
</Tip>

## Usage in API

### Importing

To use the **Mailer** package within the API, the necessary services and types need to be imported:

```typescript  theme={null}
import { Template } from 'types';
import { emailService } from 'services';
```

### Sending an Email

To send an email, the `sendTemplate` function from the `emailService` is used. This function accepts an object with properties specifying the recipient, subject line, template to be used, and an object with parameters to be filled into the template:

```typescript  theme={null}
await emailService.sendTemplate<Template.VERIFY_EMAIL>({
    to: user.email,
    subject: 'Please Confirm Your Email Address for Ship',
    template: Template.VERIFY_EMAIL,
    params: {
      firstName: user.firstName,
      href: `${config.API_URL}/account/verify-email?token=${signupToken}`,
    },
});
```

In this example, a password reset email is dispatched. The `VERIFY_EMAIL` template is used, and the user's first name and the reset password URL are passed as parameters to be substituted into the template.


# Migrator
Source: https://ship.paralect.com/docs/migrator



As the application grows your database schema also will evolve. The problem is pretty common: when you add some feature that influences a database schema(adding, removing, or replacing some fields) you will have to update already existing documents to the latest schema version. Otherwise working with old documents will be impossible, because you will struggle with errors when you will rely on an updated field in your code. So you will run migrations where you will resolve code and schema mismatching.

Migrator is a service that runs MongoDB migrations, handles versioning, and keeps logs for every migration. It performs changes/migrations to current database data, to match new schema or new requirements. Those changes are stored in the `migrator/migrations` folder.

<Tip>
  Any changes to the project's database are very sensitive and should be consistent. But also frequently migrations have operations that can take a lot of time to apply. It can create downtime for both database and API services. So to reduce these effects - Migrator is running as a separate service.
</Tip>

## How it works in the Ship

Every time Migrator is started, it is getting current successful migration version from the `migrationVersion` collection. And tries to apply every migration above this version in a sequence. Every `migration` from `migrator/migrations` will be called one by one, and every time it will be logged to the `migrationLog` collection either with:

1. `completed` status with updating the current version
2. `failed` status *without* updating the current version

<Warning>
  **Warning:** Sequence of migrations will stop on `failed` migration and won't apply versions above it.
</Warning>

## How to add a new migration.

1. To add new migration - add new `#.ts` file inside еру `migrator/migrations` folder (with the name of the next version, that is higher than the current version)ю
2. Create new `Migration` with the `#.ts` migration number and description.

### Example

We already have migration `1.ts`, so let's add another one. We have a collection of `users`, but we need to assign some of them special rights within our app. Let's add a new boolean field `isAdmin` to the user schema.

```typescript user.schema.ts theme={null}
const schema = z.object({
  _id: z.string(),
  createdOn: z.date().optional(),
  updatedOn: z.date().optional(),
  deletedOn: z.date().optional().nullable(),
  role: z.string(),
  isAdmin: z.boolean().default(false)
});
```

After adding this field to the schema, every new user will automatically have `isAdmin` upon creation with `true` or `false`.
But old users don't have the field `isAdmin` at all. So let's add it.

```typescript migrator/migrations/2.ts theme={null}
const migration = new Migration(2, 'Add isAdmin field to users');

migration.migrate = async () => {
  const userIds = await userService.distinct('_id', {
    role: 'admin',
  });

  const updateFn = (userId: string) => userService.atomic.updateOne(
    { _id: userId },
    { $set: { isAdmin: true } },
  );

  await promiseUtil.promiseLimit(userIds, 50, updateFn);
};

export default migration;
```

<Warning>
  **Warning:** Don't use methods that emit **[events](packages/node-mongo#reactivity)** during the operation. Instead, use atomic operations like **[atomic.updateOne](packages/node-mongo#atomicupdateone)** or **[updateOne](packages/node-mongo#updateconfig)** with `publishEvents: false`
</Warning>

## Promise Limit

Every migration should use `promiseLimit` to perform changes to the collections, to avoid insufficient resources to complete operations:

```typescript  theme={null}
promiseLimit(documents: unknown[], limit: number, operator: (doc: any) => any)
```

## How it deploys and runs

The main idea behind the ship's Migrator is to run it **before** **[API](api-reference/overview)** and **[Scheduler](scheduler)** deployment.
Therefore, if any migration fails, then the API or Scheduler updates will not be applied. And they will always work with an up-to-date schema.

More on **[Kubernetes](deployment/kubernetes/overview#deployment-flow)** and **[DO Apps](deployment/digital-ocean-apps#set-up-migrator-and-scheduleroptional)** deployment.

## How to re-run failed migration

Migrator always run migrations only above already applied ones.

So to re-run failed one, you simply start to migrate the process again.

For development:

```
npm run migrate-dev
```

For production:

```
npm run migrate
```

## How to check failed migration logs

First, you can check `migrationLog` and find your migration with the status `failed`. It contains the `error` and `errorStack` fields.

For Kubernetes deployment, you can check the log inside its container by:

```
kubectl get pods -A
```

which is used to check `migrator_container_name` and `namespace`, and then:

```
kubectl log -f migrator_container_name -n namespace
```


# Overview
Source: https://ship.paralect.com/docs/package-sharing/overview



Ship is monorepo, so it lets you share your code across applications to minimize duplications and reduce errors.
All shared code are inside **packages/** folder.

By default, packages include app-constants, app-types, enums, schemas and mailer. Learn more about the **mailer**  package [here](/mailer).

```shell  theme={null}
/packages
  /app-constants
  /app-types
  /enums
  /mailer
  /schemas
```

## Installation

We've included all essential packages in your apps.
If you want to add more packages, head to the `package.json` file, and in the dependencies section, add to **dependencies** package name with value "workspace:\*".

```json apps/web/package.json theme={null}
"dependencies": {
    "app-constants": "workspace:*",
    "app-types": "workspace:*",
    "schemas": "workspace:*",
  },
```

<Tip>
  The **enums** package comes with **app-types**, so no separate import is needed.
</Tip>

You can read more about **package sharing**  in [Turborepo documentation](https://turbo.build/repo/docs/handbook/sharing-code/internal-packages).


# Schemas
Source: https://ship.paralect.com/docs/package-sharing/schemas



## Overview

Schemas package contains **data schemas** for the applications, including resource schemas.

**Data schema** — is a Zod schema that defines shape of the entity. It must strictly define all fields. Resource schema is defined in entity.schema file e.x. `user.schema`.

```typescript  theme={null}
import { z } from 'zod';

import dbSchema from './db.schema';

const schema = dbSchema.extend({
  firstName: z.string(),
  lastName: z.string(),
  fullName: z.string(),

  email: z.string(),
  passwordHash: z.string().nullable().optional(),

  isEmailVerified: z.boolean().default(false),

  signupToken: z.string().nullable().optional(),
  resetPasswordToken: z.string().nullable().optional(),

  avatarUrl: z.string().nullable().optional(),
  oauth: z.object({
    google: z.boolean().default(false),
  }).optional(),

  lastRequest: z.date().optional(),
}).strict();

export default schema;
```

## Validation

Zod schemas simplify form validation in react-hook-form:

```tsx  theme={null}
import { z } from 'zod';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';

import { EMAIL_REGEX, PASSWORD_REGEX } from 'app-constants';

const schema = z.object({
  firstName: z.string().min(1, 'Please enter First name').max(100),
  lastName: z.string().min(1, 'Please enter Last name').max(100),
  email: z.string().regex(EMAIL_REGEX, 'Email format is incorrect.'),
  password: z.string().regex(PASSWORD_REGEX, 'The password must contain 6 or more characters with at least one letter (a-z) and one number (0-9).'),
});

type SignUpParams = z.infer<typeof schema>

const SignUp = () => {
    const methods = useForm<SignUpParams>({
        resolver: zodResolver(schema),
    });

    return (
        //your code here
    )
}

export default SignUp;
```

Additionally, data can be validated using the `saveParse` method:

```typescript  theme={null}
const parsed = zodSchema.saveParse(data);

if (!parsed.success) {
    throw new Error('Invalid data');
}
```

For more details on Zod, check the [documentation](https://zod.dev/).


# create-ship-app
Source: https://ship.paralect.com/docs/packages/create-ship-app



[![npm version](https://badge.fury.io/js/create-ship-app.svg)](https://badge.fury.io/js/create-ship-app)

Simple CLI tool for bootstrapping Ship applications.
Downloads actual template from Ship [monorepo](https://github.com/paralect/ship) and configures it to run.

<img src="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=b8dd3d65c41aac6cc96db19ef72637ac" alt="Init project" data-og-width="739" width="739" data-og-height="748" height="748" data-path="images/init-project.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=280&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=1d4182a699988dcdc7a062792ed64a55 280w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=560&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=f11b56dd940643183fb357af5deb5055 560w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=840&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=800d987b87f99226ed191324417de1e1 840w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1100&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=a0f335955aa56a7c66000bff6c225ad1 1100w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=1650&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=6de7c05d7d4ed5cba27cb7d9d157f797 1650w, https://mintcdn.com/ship/aSd7_VT7diYXG7bS/images/init-project.png?w=2500&fit=max&auto=format&n=aSd7_VT7diYXG7bS&q=85&s=220330c4c1229776bc2ccd165003c646 2500w" />

## Build options

### Deployment type

* [**Digital Ocean Apps**](/deployment/digital-ocean-apps)
* [**Render**](/deployment/render)
* [**Digital Ocean Managed Kubernetes**](/deployment/kubernetes/digital-ocean)
* [**AWS EKS**](/deployment/kubernetes/aws)

## Usage

```shell  theme={null}
npx create-ship-app@latest init
```

or

```shell  theme={null}
npx create-ship-app@latest my-project
```


# Events
Source: https://ship.paralect.com/docs/packages/node-mongo/api-reference/events

Events API reference

### `eventBus.on`

```typescript  theme={null}
on: (
  eventName: string,
  handler: InMemoryEventHandler,
): void
```

```typescript  theme={null}
import { eventBus, InMemoryEvent } from '@paralect/node-mongo';

const collectionName = 'users';

eventBus.on(`${collectionName}.created`, (data: InMemoryEvent<User>) => {
  try {
    const user = data.doc;

    console.log('user created', user);
  } catch (err) {
    logger.error(`${USERS}.created handler error: ${err}`);
  }
});

eventBus.on(`${collectionName}.updated`, (data: InMemoryEvent<User>) => {});

eventBus.on(`${collectionName}.deleted`, (data: InMemoryEvent<User>) => {});
```

In-memory events handler that listens for a CUD events.

**Parameters**

* eventName: `string`;\
  Events names to listen.\
  Valid format: `${collectionName}.created`, `${collectionName}.updated`, `${collectionName}.deleted`.
* handler: [`InMemoryEventHandler`](#inmemoryeventhandler);

**Returns** `void`.

### `eventBus.once`

```typescript  theme={null}
once: (
  eventName: string,
  handler: InMemoryEventHandler,
): void
```

```typescript  theme={null}
eventBus.once(`${USERS}.updated`, (data: InMemoryEvent<User>) => {
  try {
    const user = data.doc;

    console.log('user updated', user);
  } catch (err) {
    logger.error(`${USERS}.updated handler error: ${err}`);
  }
});
```

In-memory events handler that listens for a CUD events. **It will be called only once**.

**Parameters**

* eventName: `string`;\
  Events names to listen.\
  Valid format: `${collectionName}.created`, `${collectionName}.updated`, `${collectionName}.deleted`.
* handler: [`InMemoryEventHandler`](#inmemoryeventhandler);

**Returns** `void`.

### `eventBus.onUpdated`

```typescript  theme={null}
onUpdated: (
  entity: string,
  properties: OnUpdatedProperties,
  handler: InMemoryEventHandler,
): void
```

```typescript  theme={null}
import { eventBus, InMemoryEvent } from '@paralect/node-mongo';

eventBus.onUpdated('users', ['firstName', 'lastName'], async (data: InMemoryEvent<User>) => {
  try {
    await userService.atomic.updateOne(
      { _id: data.doc._id },
      { $set: { fullName: `${data.doc.firstName} ${data.doc.lastName}` } },
    );
  } catch (err) {
    console.log(`users onUpdated ['firstName', 'lastName'] handler error: ${err}`);
  }
});

eventBus.onUpdated('users', [{ fullName: 'John Wake', firstName: 'John' }, 'lastName'], () => {});

eventBus.onUpdated('users', ['oauth.google'], () => {});
```

In-memory events handler that listens for specific fields updates. It will be called when one of the provided `properties` updates.

**Parameters**

* entity: `string`;\
  Collection name for events listening.
* properties: [`OnUpdatedProperties`](#onupdatedproperties);\
  Properties whose update will trigger the event.
* handler: [`InMemoryEventHandler`](#inmemoryeventhandler);

**Returns** `void`.


# Service
Source: https://ship.paralect.com/docs/packages/node-mongo/api-reference/service

Service API reference

### `find`

```typescript  theme={null}
find = async <U extends T = T>(
  filter: Filter<U>,
  readConfig: ReadConfig & { page?: number; perPage?: number } = {},
  findOptions: FindOptions = {},
): Promise<FindResult<U>>
```

```typescript  theme={null}
const { results: users, count: usersCount } = await userService.find(
  { status: 'active' },
);
```

Fetches documents that matches the filter. Returns an object with the following fields(`FindResult`):

| Field      | Description                                                                                    |
| ---------- | ---------------------------------------------------------------------------------------------- |
| results    | documents, that matches the filter                                                             |
| count      | total number of documents, that matches the filter                                             |
| pagesCount | total number of documents, that matches the filter divided by the number of documents per page |

Pass `page` and `perPage` params to get a paginated result. Otherwise, all documents will be returned.

**Parameters**

* filter: [`Filter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* readConfig: [`ReadConfig`](#readconfig) `& { page?: number; perPage?: number }`;
* findOptions: [`FindOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/FindOptions.html);

**Returns** `Promise<FindResult<U>>`.

### `findOne`

```typescript  theme={null}
findOne = async <U extends T = T>(
  filter: Filter<U>,
  readConfig: ReadConfig = {},
  findOptions: FindOptions = {},
): Promise<U | null>
```

```typescript  theme={null}
const user = await userService.findOne({ _id: u._id });
```

Fetches the first document that matches the filter. Returns `null` if document was not found.

**Parameters**

* filter: [`Filter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* readConfig: [`ReadConfig`](#readconfig);
* findOptions: [`FindOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/FindOptions.html);

**Returns** `Promise<U | null>`.

### `updateOne`

```typescript  theme={null}
updateOne = async <U extends T = T>(
  filter: Filter<U>,
  updateFilterOrFn: (doc: U) => Partial<U> | UpdateFilter<U>,
  updateConfig: UpdateConfig = {},
  updateOptions: UpdateOptions = {},
): Promise<U | null>
```

```typescript  theme={null}
const updatedUserWithEvent = await userService.updateOne(
  { _id: u._id },
  (doc) => ({ fullName: 'Updated fullname' }),
);

const updatedUser = await userService.updateOne(
  { _id: u._id },
  (doc) => ({ fullName: 'Updated fullname' }),
  { publishEvents: false }
);

const updatedUserWithUpdateFilter = await userService.updateOne(
  { _id: u._id },
  { $set: { fullName: 'Updated fullname' }},
);
```

Updates a single document and returns it. Returns `null` if document was not found.

**Parameters**

* filter: [`Filter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* updateFilterOrFn: `(doc: U) => Partial<U>` | [`UpdateFilter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#UpdateFilter);
  Function that accepts current document and returns object containing fields to update.
* updateConfig: [`UpdateConfig`](#updateconfig);
* updateOptions: [`UpdateOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/UpdateOptions.html);

**Returns** `Promise<U | null>`.

### `updateMany`

```typescript  theme={null}
updateMany = async <U extends T = T>(
  filter: Filter<U>,
  updateFilterOrFn: (doc: U) => Partial<U> | UpdateFilter<U>,
  updateConfig: UpdateConfig = {},
  updateOptions: UpdateOptions = {},
): Promise<U[]>
```

```typescript  theme={null}
const updatedUsers = await userService.updateMany(
  { status: 'active' },
  (doc) => ({ isEmailVerified: true }),
);

const updatedUsersWithUpdateFilter = await userService.updateMany(
  { status: 'active' },
  { $set: { isEmailVerified: true } },
);
```

Updates multiple documents that match the query. Returns array with updated documents.

**Parameters**

* filter: [`Filter<U>`](https://mongodb.github.io/node-mongodb-native/4.7/modules.html#Filter);
* updateFilterOrFn: `(doc: U) => Partial<U>` | [`UpdateFilter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#UpdateFilter);\
  Function that accepts current document and returns object containing fields to update.
* updateConfig: [`UpdateConfig`](#updateconfig);
* updateOptions: [`UpdateOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/UpdateOptions.html);

**Returns** `Promise<U[]>`.

### `insertOne`

```typescript  theme={null}
insertOne = async <U extends T = T>(
  object: Partial<U>,
  createConfig: CreateConfig = {},
  insertOneOptions: InsertOneOptions = {},
): Promise<U>
```

```typescript  theme={null}
const user = await userService.insertOne({
  fullName: 'John',
});
```

Inserts a single document into a collection and returns it.

**Parameters**

* object: `Partial<U>`;
* createConfig: [`CreateConfig`](#createconfig);
* insertOneOptions: [`InsertOneOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/InsertOneOptions.html);

**Returns** `Promise<U>`.

### `insertMany`

```typescript  theme={null}
insertMany = async <U extends T = T>(
  objects: Partial<U>[],
  createConfig: CreateConfig = {},
  bulkWriteOptions: BulkWriteOptions = {},
): Promise<U[]>
```

```typescript  theme={null}
const users = await userService.insertMany([
  { fullName: 'John' },
  { fullName: 'Kobe' },
]);
```

Inserts multiple documents into a collection and returns them.

**Parameters**

* objects: `Partial<U>[]`;
* createConfig: [`CreateConfig`](#createconfig);
* bulkWriteOptions: [`BulkWriteOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/BulkWriteOptions.html);

**Returns** `Promise<U[]>`.

### `deleteSoft`

```typescript  theme={null}
deleteSoft = async <U extends T = T>(
  filter: Filter<U>,
  deleteConfig: DeleteConfig = {},
  deleteOptions: DeleteOptions = {},
): Promise<U[]>
```

```typescript  theme={null}
const deletedUsers = await userService.deleteSoft(
  { status: 'deactivated' },
);
```

Adds `deletedOn` field to the documents that match the query and returns them.

**Parameters**

* filter: [`Filter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* deleteConfig: [`DeleteConfig`](#deleteconfig);
* deleteOptions: [`DeleteOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/DeleteOptions.html);

**Returns** `Promise<U[]>`.

### `deleteOne`

```typescript  theme={null}
deleteOne = async <U extends T = T>(
  filter: Filter<U>,
  deleteConfig: DeleteConfig = {},
  deleteOptions: DeleteOptions = {},
): Promise<U | null>
```

```typescript  theme={null}
const deletedUser = await userService.deleteOne(
  { _id: u._id },
);
```

Deletes a single document and returns it. Returns `null` if document was not found.

**Parameters**

* filter: [`Filter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* deleteConfig: [`DeleteConfig`](#deleteconfig);
* deleteOptions: [`DeleteOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/DeleteOptions.html);

**Returns** `Promise<U | null>`.

### `deleteMany`

```typescript  theme={null}
deleteMany = async <U extends T = T>(
  filter: Filter<U>,
  deleteConfig: DeleteConfig = {},
  deleteOptions: DeleteOptions = {},
): Promise<U[]>
```

```typescript  theme={null}
const deletedUsers = await userService.deleteMany(
  { status: 'deactivated' },
);
```

Deletes multiple documents that match the query. Returns array with deleted documents.

**Parameters**

* filter: [`Filter<U>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* deleteConfig: [`DeleteConfig`](#deleteconfig);
* deleteOptions: [`DeleteOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/DeleteOptions.html);

**Returns** `Promise<U[]>`.

### `replaceOne`

```typescript  theme={null}
replaceOne: (
  filter: Filter<T>,
  replacement: Partial<T>,
  readConfig: ReadConfig = {},
  replaceOptions: ReplaceOptions = {},
): Promise<UpdateResult | Document>
```

```typescript  theme={null}
await usersService.replaceOne(
  { _id: u._id },
  { fullName: fullNameToUpdate },
);
```

Replaces a single document within the collection based on the filter. **Doesn't validate schema or publish events**.

**Parameters**

* filter: [`Filter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* replacement: `Partial<T>`;
* readConfig: [`ReadConfig`](#readconfig);
* replaceOptions: [`ReplaceOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/ReplaceOptions.html);

**Returns** `Promise<`[UpdateResult](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/UpdateResult.html) `|` [Document](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/Document.html)`>`.

### `atomic.updateOne`

```typescript  theme={null}
updateOne: (
  filter: Filter<T>,
  updateFilter: UpdateFilter<T>,
  readConfig: ReadConfig = {},
  updateOptions: UpdateOptions = {},
): Promise<UpdateResult>
```

```typescript  theme={null}
await userService.atomic.updateOne(
  { _id: u._id },
  { $set: { fullName: `${u.firstName} ${u.lastName}` } },
);
```

Updates a single document. **Doesn't validate schema or publish events**.

**Parameters**

* filter: [`Filter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* updateFilter: [`UpdateFilter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#UpdateFilter);
* readConfig: [`ReadConfig`](#readconfig);
* updateOptions: [`UpdateOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/UpdateOptions.html);

**Returns** `Promise<`[UpdateResult](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/UpdateResult.html)`>`.

### `atomic.updateMany`

```typescript  theme={null}
updateMany: (
  filter: Filter<T>,
  updateFilter: UpdateFilter<T>,
  readConfig: ReadConfig = {},
  updateOptions: UpdateOptions = {},
): Promise<Document | UpdateResult>
```

```typescript  theme={null}
await userService.atomic.updateMany(
  { firstName: { $exists: true }, lastName: { $exists: true } },
  { $set: { fullName: `${u.firstName} ${u.lastName}` } },
);
```

Updates all documents that match the specified filter. **Doesn't validate schema or publish events**.

**Parameters**

* filter: [`Filter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* updateFilter: [`UpdateFilter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#UpdateFilter);
* readConfig: [`ReadConfig`](#readconfig);
* updateOptions: [`UpdateOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/UpdateOptions.html);

**Returns** `Promise<`[UpdateResult](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/UpdateResult.html) `|` [Document](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/Document.html)`>`.

### `exists`

```typescript  theme={null}
exists(
  filter: Filter<T>,
  readConfig: ReadConfig = {},
  findOptions: FindOptions = {},
): Promise<boolean>
```

```typescript  theme={null}
const isUserExists = await userService.exists(
  { email: 'example@gmail.com' },
);
```

Returns ***true*** if document exists, otherwise ***false***.

**Parameters**

* filter: [`Filter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* readConfig: [`ReadConfig`](#readconfig);
* findOptions: [`FindOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/FindOptions.html);

**Returns** `Promise<boolean>`.

### `countDocuments`

```typescript  theme={null}
countDocuments(
  filter: Filter<T>,
  readConfig: ReadConfig = {},
  countDocumentOptions: CountDocumentsOptions = {},
): Promise<boolean>
```

```typescript  theme={null}
const documentsCount = await userService.countDocuments(
  { status: 'active' },
);
```

Returns amount of documents that matches the query.

**Parameters**

* filter: [`Filter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* readConfig: [`ReadConfig`](#readconfig);
* countDocumentOptions: [`CountDocumentsOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/CountDocumentsOptions.html);

**Returns** `Promise<number>`.

### `distinct`

```typescript  theme={null}
distinct(
  key: string,
  filter: Filter<T>,
  readConfig: ReadConfig = {},
  distinctOptions: DistinctOptions = {},
): Promise<any[]>
```

```typescript  theme={null}
const statesList = await userService.distinct('states');
```

Returns distinct values for a specified field across a single collection or view and returns the results in an array.

**Parameters**

* key: `string`;
* filter: [`Filter<T>`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#Filter);
* readConfig: [`ReadConfig`](#readconfig);
* distinctOptions: [`DistinctOptions`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#DistinctOptions);

**Returns** `Promise<any[]>`.

### `aggregate`

```typescript  theme={null}
aggregate: (
  pipeline: any[],
  options: AggregateOptions = {},
): Promise<any[]>
```

```typescript  theme={null}
const sortedActiveUsers = await userService.aggregate([
  { $match: { status: "active" } },
  { $sort: { firstName: -1, lastName: -1 } }
]);
```

Executes an aggregation framework pipeline and returns array with aggregation result of documents.

**Parameters**

* pipeline: `any[]`;
* options: [`AggregateOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/AggregateOptions.html);

**Returns** `Promise<any[]>`.

### `watch`

```typescript  theme={null}
watch: (
  pipeline: Document[] | undefined,
  options: ChangeStreamOptions = {},
): Promise<any>
```

```typescript  theme={null}
const watchCursor = userService.watch();
```

Creates a new Change Stream, watching for new changes and returns a cursor.

**Parameters**

* pipeline: `Document[] | undefined`;
* options: [`ChangeStreamOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/ChangeStreamOptions.html);

**Returns** `Promise<any>`.

### `drop`

```typescript  theme={null}
drop: (
  recreate: boolean = false,
): Promise<void>
```

```typescript  theme={null}
await userService.drop();
```

Removes a collection from the database. The method also removes any indexes associated with the dropped collection.

**Parameters**

* recreate: `boolean`;
  Should create collection after deletion.

**Returns** `Promise<void>`.

### `indexExists`

```typescript  theme={null}
indexExists: (
  indexes: string | string[],
  indexInformationOptions: IndexInformationOptions = {},
): Promise<boolean>
```

```typescript  theme={null}
const isIndexExists = await usersService.indexExists(index);
```

Checks if one or more indexes exist on the collection, fails on first non-existing index.

**Parameters**

* indexes: `string | string[]`;
* indexInformationOptions: [`IndexInformationOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/IndexInformationOptions.html);

**Returns** `Promise<string | void>`.

### `createIndex`

```typescript  theme={null}
createIndex: (
  indexSpec: IndexSpecification,
  options: CreateIndexesOptions = {},
): Promise<string | void>
```

```typescript  theme={null}
await usersService.createIndex({ fullName: 1 });
```

Creates collection index.

**Parameters**

* indexSpec: [`IndexSpecification`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#IndexSpecification);
* options: [`CreateIndexesOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/CreateIndexesOptions.html);

**Returns** `Promise<string | void>`.

### `createIndexes`

```typescript  theme={null}
createIndexes: (
  indexSpecs: IndexDescription[],
  options: CreateIndexesOptions = {},
): Promise<string[] | void>
```

```typescript  theme={null}
await usersService.createIndexes([
  { key: { fullName: 1 } },
  { key: { createdOn: 1 } },
]);
```

Creates one or more indexes on a collection.

**Parameters**

* indexSpecs: [`IndexDescription[]`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#IndexSpecification);
* options: [`CreateIndexesOptions`](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/CreateIndexesOptions.html);

**Returns** `Promise<string[] | void>`.

### `dropIndex`

```typescript  theme={null}
dropIndex: (
  indexName: string,
  options: DropIndexesOptions = {},
): Promise<void | Document>
```

```typescript  theme={null}
await userService.dropIndex({ firstName: 1, lastName: -1 });
```

Removes the specified index from a collection.

**Parameters**

* indexName: `string`;
* options: [`DropIndexesOptions`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#DropIndexesOptions);

**Returns** `Promise<void | Document>`.

### `dropIndexes`

```typescript  theme={null}
dropIndexes: (
  options: DropIndexesOptions = {},
): Promise<void | Document>
```

Removes all but the `_id` index from a collection.

```typescript  theme={null}
await userService.dropIndexes();
```

**Parameters**

* options: [`DropIndexesOptions`](https://mongodb.github.io/node-mongodb-native/4.10/modules.html#DropIndexesOptions);

**Returns** `Promise<void | Document>`.


# Transactions
Source: https://ship.paralect.com/docs/packages/node-mongo/api-reference/transactions

Transactions API reference

### `withTransaction`

```typescript  theme={null}
withTransaction: <TRes = any>(
  transactionFn: (session: ClientSession) => Promise<TRes>,
): Promise<TRes>
```

Runs callbacks and automatically commits or rollbacks transaction.

```typescript  theme={null}
import db from 'db';

const { user, company } = await db.withTransaction(async (session) => {
  const createdUser = await usersService.insertOne({ fullName: 'Bahrimchuk' }, {}, { session });
  const createdCompany = await companyService.insertOne(
    { users: [createdUser._id] }, {},
    { session },
  );

  return { user: createdUser, company: createdCompany };
});
```

**Parameters**

* transactionFn: `(session: ClientSession) => Promise<TRes>`;\
  Function that accepts a client session and manages some business logic. Must return a `Promise`.

**Returns** `Promise<TRes>`.


# Changelog
Source: https://ship.paralect.com/docs/packages/node-mongo/changelog

Release history and updates for the node-mongo package.

<Update label="v3.3.0" description="July 15, 2025">
  * You can now pass TypeScript generics to all service methods for precise type inference and enhanced type safety. This helps you catch mistakes at compile time and improves your development experience.

  ```typescript  theme={null}
  const user = await userService.findOne({ _id: '...' });

  // user.subscription is available if defined in schema
  user.subscription

  // Pass a generic to override the provided type
  // TypeScript will enforce the structure you specify:
  const admin = await userService.findOne<Admin>({ _id: '...' });

  // TypeScript Error:
  // Property 'subscription' doesn't exist on type 'Admin'
  admin.subscription
  ```

  * Added `escapeRegExp` option to service methods, enabling automatic escaping of `$regex` filter values to prevent special characters from being interpreted as patterns.

  Before

  ```typescript  theme={null}
  const users = await userService.find({
    name: { $regex: 'John\' }, 
  });

  // Throws error 'Regular expression is invalid: \\ at end of pattern'
  // Provided string by user needs to be escaped before query
  ```

  After

  ```typescript {3} theme={null}
  const service = db.createService<User>(DATABASE_DOCUMENTS.USERS, {
    schemaValidator: (obj) => userSchema.parseAsync(obj),
    escapeRegExp: true,
  });

  // No need to escape string before query
  const users = await userService.find({
    name: { $regex: 'John\' },
  });
  ```

  * Upgraded `mongodb` dependency to v6.17.0 and updated related dependencies (mocha, @types/mocha, zod, etc.).
  * Fixed all known vulnerabilities.
</Update>

<Update label="v3.2.0" description="October 10, 2023">
  * Upgraded `mongodb` dependency from v4.10.0 to v6.1.0 (requires Node.js >=16.16.0).
  * Cleaned up legacy MongoDB connection options.
  * Improved typings and compatibility for bulk operations and index management.
</Update>

<Update label="v3.1.2" description="December 1, 2022">
  * Synchronized README.md with the documentation website for consistency and completeness.
</Update>

<Update label="v3.1.1" description="October 24, 2022">
  * Fixed: `atomic.updateOne` and `atomic.updateMany` now use `readConfig` for query validation, ensuring consistent handling of soft-delete and query options.
</Update>

<Update label="v3.1.0" description="October 17, 2022">
  * Refactored `Service` and `Database` classes for better type safety:
    * `IDocument` now extends MongoDB's `Document` and requires `_id: string`.
    * Many methods now use stricter generic constraints (`<T extends IDocument>`).
  * Added support for custom schema validation via `schemaValidator` in `ServiceOptions`.
  * Introduced new config types: `CreateConfig`, `ReadConfig`, `UpdateConfig`, `DeleteConfig` for more granular operation control.
  * Improved transaction support: `database.withTransaction` now uses default transaction options and better error handling.
  * Enhanced logging for event publishing and warnings in development mode.
  * Internal: Cleaned up and unified method signatures, improved property type checks, and removed legacy/duplicate code.
</Update>

<Update label="v3.0.4" description="September 7, 2022">
  * Changed all date fields (`createdOn`, `updatedOn`, `deletedOn`) to use native `Date` objects instead of ISO strings.
</Update>

<Update label="v3.0.3" description="August 3, 2022">
  * `service.find()` options `page` and `perPage` are now optional; defaults are set internally if omitted.
</Update>

<Update label="v3.0.2" description="June 24, 2022">
  * `eventBus.onUpdated` now supports generics for improved type safety.
  * `service.aggregate()` now returns an array of results directly.
</Update>

<Update label="v3.0.1" description="June 21, 2022">
  * In-memory event listeners now require an entity name (e.g., `onUpdated('users', ...)`).
  * Added logging for published in-memory events.
</Update>

<Update label="v3.0.0" description="March 28, 2022">
  The release includes a lot of changes to make sure that the package is compatible with the latest MongoDB version.
  Most notable changes:

  * Rewritten in TypeScript
  * Removed [monk](https://github.com/Automattic/monk) dependency.
  * Added [mongodb native Node.JS sdk](https://www.mongodb.com/docs/drivers/node/current/) as dependency.
  * Added support for transactional events using [transactional outbox pattern](https://microservices.io/patterns/data/transactional-outbox.html)
  * Introduced shared in-memory events bus. It should be used to listen for CUD updates.
</Update>

<Update label="v2.1.0" description="October 15, 2020">
  ### Features

  #### Manager

  [createService](API.md#createservice)

  * Add [emitter](API.md#createservice) option.
</Update>

<Update label="v2.0.0" description="September 29, 2020">
  * Update dependencies.

  ### Breaking Changes

  #### [Manager](API.md#manager)

  [createQueryService](API.md#createqueryservice)

  * Rename `validateSchema` option to `validate`.
  * Change `addCreatedOnField` default to `true`.
  * Change `addUpdatedOnField` default to `true`.

  [createService](API.md#createservice)

  * Rename `validateSchema` option to `validate`.
  * Change `addCreatedOnField` default to `true`.
  * Change `addUpdatedOnField` default to `true`.

  #### [Query Service](API.md#query-service)

  * Remove `generateId` method.
  * Remove `expectDocument` method.

  #### [Service](API.md#service)

  * Remove `update` method. Use [updateOne](API.md#updateone) or [updateMany](API.md#updatemany).
  * Remove `ensureIndex`. Use [atomic.createIndex](API.md#atomiccreateindex).
  * Remove `createOrUpdate`. Use [create](API.md#create) or [updateOne](API.md#updateone) or [updateMany](API.md#updatemany).
  * Remove `findOneAndUpdate`. Use [findOne](API.md#findone) and [updateOne](API.md#updateone).

  ### Features

  #### Manager

  [createQueryService](API.md#createqueryservice)

  * Add `useStringId` option.

  [createService](API.md#createservice)

  * Add `useStringId` option.

  #### [Query Service](API.md#query-service)

  * Add more monk's methods. [See full list](API.md#query-service)

  #### [Service](API.md#service)

  * Add [generateId](API.md#generateid) method.
  * Add [updateOne](API.md#updateone) method.
  * Add [updateMany](API.md#updatemany) method.
  * Add [performTransaction](API.md#performtransaction) method.
  * Add more monk's methods in `atomic` namespace. [See full list](API.md#service)
</Update>

<Update label="v1.1.0" description="June 25, 2019">
  * Update dependencies.
  * Fix required version of the Node.js.

  ### Breaking Changes

  * Now `update` function will work via [set](https://docs.mongodb.com/manual/reference/operator/update/set/) operator. It means the new doc will be the result of merge of the old doc and the provided one.
</Update>

<Update label="v1.0.0" description="May 23, 2018">
  * Update dependencies.
  * Add tests.
  * Fix required version of the Node.js.

  ### Breaking Changes

  * Now, by default, we do not add the fields `createdOn` and` updatedOn` automatically to the model. If you want to save the current behavior, add the appropriate `addCreatedOnField` and` addUpdatedOnField` options to the service definitions.
</Update>

<Update label="v0.3.1" description="December 16, 2017">
  * Stop using deprecated method `ensureIndex` of the `monk`.
</Update>

<Update label="v0.3.0" description="October 24, 2017">
  * Add ability to create custom methods for service and query service.
  * Add tests.
</Update>

<Update label="v0.2.0" description="October 12, 2017">
  * Add support of the [joi](https://github.com/hapijs/joi) for validating data schema.
  * Add tests for validating of the schema.
</Update>


# Overview
Source: https://ship.paralect.com/docs/packages/node-mongo/overview



[![npm version](https://badge.fury.io/js/%40paralect%2Fnode-mongo.svg)](https://badge.fury.io/js/%40paralect%2Fnode-mongo)

Lightweight reactive extension to official Node.js MongoDB [driver](https://mongodb.github.io/node-mongodb-native/4.10/).

## Features

* **ObjectId mapping**. Automatically converts the `_id` field from the `ObjectId` to a `string`.
* ️️**Reactive**. Fires events as a document created, updated, or deleted from the database;
* **CUD operations timestamps**. Automatically sets `createdOn`, `updatedOn`, and `deletedOn` timestamps for CUD operations;
* **Schema validation**. Validates your data before saving;
* **Paging**. Implements high-level paging API;
* **Soft delete**. By default, documents don't remove from the collection, but are marked with the `deletedOn` field;
* **Extendable**. API is easily extendable, you can add new methods or override existing ones;
* **Outbox support**. node-mongo can create collections with `_outbox` postfix that stores all CUD events for implementing the [transactional outbox](about:blank) pattern;

The following example shows some of these features:

```typescript  theme={null}
import { eventBus, InMemoryEvent } from '@paralect/node-mongo';

await userService.updateOne(
  { _id: '62670b6204f1aab85e5033dc' },
  (doc) => ({ firstName: 'Mark' }),
);

eventBus.onUpdated('users', ['firstName', 'lastName'], async (data: InMemoryEvent<User>) => {
  await userService.atomic.updateOne(
    { _id: data.doc._id },
    { $set: { fullName: `${data.doc.firstName} ${data.doc.lastName}` } },
  );
});
```

## Installation

```
npm i @paralect/node-mongo
```

## Connect to Database

Usually, you need to define a file called `db` that does two things:

1. Creates database instance and connects to the database;
2. Exposes factory method `createService` to create different [Services](#services) to work with MongoDB;

```typescript db.ts theme={null}
import { Database, Service, ServiceOptions, IDocument } from '@paralect/node-mongo';

import config from 'config';

const database = new Database(config.mongo.connection, config.mongo.dbName);
database.connect();

class CustomService<T extends IDocument> extends Service<T> {
  // You can add new methods or override existing here
}

function createService<T extends IDocument>(collectionName: string, options: ServiceOptions = {}) {
  return new CustomService<T>(collectionName, database, options);
}

export default {
  database,
  createService,
};
```

## Services

Service is a collection wrapper that adds all node-mongo features. Under the hood it uses Node.js MongoDB native methods.

`createService` method returns the service instance. It accepts two parameters: collection name and [ServiceOptions](#serviceoptions).

```typescript user.service.ts theme={null}
import { z } from 'zod';

import db from 'db';

const schema = z.object({
  _id: z.string(),
  createdOn: z.date().optional(),
  updatedOn: z.date().optional(),
  deletedOn: z.date().optional().nullable(),
  fullName: z.string(),
}).strict();

type User = z.infer<typeof schema>;

const service = db.createService<User>('users', {
  schemaValidator: (obj) => schema.parseAsync(obj),
});

export default service;
```

```typescript update-user.ts theme={null}
import userService from 'user.service';

await userService.insertOne({ fullName: 'Max' });
```

## Schema validation

Node-mongo supports any schema library, but we recommend [Zod](https://zod.dev/), due to this ability to generate TypeScript types from the schemas.

### Zod

```typescript  theme={null}
const schema = z.object({
  _id: z.string(),
  createdOn: z.date().optional(),
  updatedOn: z.date().optional(),
  deletedOn: z.date().optional().nullable(),
  fullName: z.string(),
});

type User = z.infer<typeof schema>;

const service = createService<User>('users', {
  schemaValidator: (obj) => schema.parseAsync(obj),
});
```

### Joi

```typescript  theme={null}
const schema = Joi.object({
  _id: Joi.string().required(),
  createdOn: Joi.date(),
  updatedOn: Joi.date(),
  deletedOn: Joi.date().allow(null),
  fullName: Joi.string().required(),
});

type User = {
  _id: string;
  createdOn?: Date;
  updatedOn?: Date;
  deletedOn?: Date | null;
  fullName: string;
};

const service = createService<User>('users', {
  schemaValidator: (obj) => schema.validateAsync(obj),
});

```

<Tip>
  Node-mongo validates documents before save.
</Tip>

## Reactivity

The key feature of the `node-mongo` is that each create, update or delete operation publishes a CUD event.

* `${collectionName}.created`
* `${collectionName}.updated`
* `${collectionName}.deleted`

Events are used to easily update denormalized data and also to implement complex business logic without tight coupling of different entities.

SDK support two type of events:

### In-memory events

* Enabled by default;
* Events can be lost on service failure;
* Events are stored in `eventBus` (Node.js [EventEmitter](https://nodejs.org/api/events.html#events) instance);
* For handling these events type you will use [Events API](#events);
* Designed for transferring events inside a single Node.js process. Events handlers listens node-mongo `eventBus`.

### Transactional events

* Can be enabled by setting `{ outbox: true }` when creating a service;
* Guarantee that every database write will produce an event;
* Events are stored in special collections with `_outbox` postfix;
* For handling these events type you will use `watch` (method for working with Change Streams) on the outbox table;
* Designed for transferring events to messages broker like Kafka. Events handlers should listen to message broker events (You need to implement this layer yourself).

<Tip>
  On the project start, we recommend using `in-memory` events. When your application becomes tougher you should migrate to `transactional` events.
</Tip>

## Options and Types

### `ServiceOptions`

```typescript  theme={null}
interface ServiceOptions {
  skipDeletedOnDocs?: boolean,
  schemaValidator?: (obj: any) => Promise<any>,
  publishEvents?: boolean,
  addCreatedOnField?: boolean,
  addUpdatedOnField?: boolean,
  outbox?: boolean,
  collectionOptions?: CollectionOptions;
  collectionCreateOptions?: CreateCollectionOptions;
}
```

| Option                    | Description                                                                                                                   | Default value |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `skipDeletedOnDocs`       | Skip documents with the `deletedOn` field                                                                                     | `true`        |
| `schemaValidator`         | Validation function that will be called on data save                                                                          | -             |
| `publishEvents`           | Publish [CUD events](#reactivity) on save.                                                                                    | `true`        |
| `addCreatedOnField`       | Set the `createdOn` field to the current timestamp on document creation.                                                      | `true`        |
| `addUpdatedOnField`       | Set `updateOne` field to the current timestamp on the document update.                                                        | `true`        |
| `outbox`                  | Use [transactional](#transactional-events) events instead of [in-memory events](#in-memory-events)                            | `false`       |
| `escapeRegExp`            | Escape `$regex` values to prevent special characters from being interpreted as patterns.                                      | `false`       |
| `collectionOptions`       | MongoDB [CollectionOptions](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/CollectionOptions.html)             | `{}`          |
| `collectionCreateOptions` | MongoDB [CreateCollectionOptions](https://mongodb.github.io/node-mongodb-native/4.10/interfaces/CreateCollectionOptions.html) | `{}`          |

### `CreateConfig`

Overrides `ServiceOptions` parameters for create operations.

```typescript  theme={null}
type CreateConfig = {
  validateSchema?: boolean,
  publishEvents?: boolean,
};
```

### `ReadConfig`

Overrides `ServiceOptions` parameters for read operations.

```typescript  theme={null}
type ReadConfig = {
  skipDeletedOnDocs?: boolean,
};
```

### `UpdateConfig`

Overrides `ServiceOptions` parameters for update operations.

```typescript  theme={null}
type UpdateConfig = {
  skipDeletedOnDocs?: boolean,
  validateSchema?: boolean,
  publishEvents?: boolean,
};
```

### `DeleteConfig`

Overrides `ServiceOptions` parameters for delete operations.

```typescript  theme={null}
type DeleteConfig = {
  skipDeletedOnDocs?: boolean,
  publishEvents?: boolean,
};
```

### `InMemoryEvent`

```typescript  theme={null}
type InMemoryEvent<T = any> = {
  doc: T,
  prevDoc?: T,
  name: string,
  createdOn: Date
};
```

### `InMemoryEventHandler`

```typescript  theme={null}
type InMemoryEventHandler = (evt: InMemoryEvent) => Promise<void> | void;
```

### `OnUpdatedProperties`

```typescript  theme={null}
type OnUpdatedProperties = Array<Record<string, unknown> | string>;
```

## Extending API

Extending API for a single service.

```typescript  theme={null}
const service = db.createService<User>('users', {
  schemaValidator: (obj) => schema.parseAsync(obj),
});

const privateFields = [
  'passwordHash',
  'signupToken',
  'resetPasswordToken',
];

const getPublic = (user: User | null) => _.omit(user, privateFields);

export default Object.assign(service, {
  updateLastRequest,
  getPublic,
});
```

Extending API for all services.

```typescript  theme={null}
const database = new Database(config.mongo.connection, config.mongo.dbName);

class CustomService<T extends IDocument> extends Service<T> {
  createOrUpdate = async (query: any, updateCallback: (item?: T) => Partial<T>) => {
    const docExists = await this.exists(query);

    if (!docExists) {
      const newDoc = updateCallback();
      return this.insertOne(newDoc);
    }

    return this.updateOne(query, (doc) => updateCallback(doc));
  };
}

function createService<T extends IDocument>(collectionName: string, options: ServiceOptions = {}) {
  return new CustomService<T>(collectionName, database, options);
}

const userService = createService<UserType>('users', {
  schemaValidator: (obj) => schema.parseAsync(obj),
});

await userService.createOrUpdate(
  { _id: 'some-id' },
  () => ({ fullName: 'Max' }),
);
```


# Retool
Source: https://ship.paralect.com/docs/retool



## Installation guideline

1. Create an account at [Retool](https://login.retool.com/auth/signup) or request an invite to the existing project. At the moment Retool doesn't allow users to have multiple projects. So keep in mind that it's impossible to use one account on different projects.

2. Download the following `JSON` [config for users management](https://ship-docs.fra1.cdn.digitaloceanspaces.com/retool/users-management.json)

3. Import prebuilt applications: open `Apps` > ` Create New` > `From JSON` and choose downloaded file above.

<video controls className="w-full aspect-video" src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/video/retool/import-project.mp4?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=17d7d806b841b6caef30bc9a4bb1c059" data-path="video/retool/import-project.mp4" />

3. Attach resources (API or Database) for performing Retool queries: СRUD operations with data, HTTP requests, etc. Select the query, click on `Resource` and choose one. Look at the [App Resources](#app-resources) section to see how to connect different types of resources.

<video controls className="w-full aspect-video" src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/video/retool/update-resources.mp4?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=772db08e16d756eb0cdc866bacccf687" data-path="video/retool/update-resources.mp4" />

<Tip>
  Learn how to build more with Retool [documentation](https://docs.retool.com/docs/home).
</Tip>

## Predefined Apps

### Users Management App

The application is built for user administration, it can be extended and used as internal admin panel. The main features are:

* Users are displayed in the table.
* You can find a particular user.
* You can see the user's details and apply a set of actions to the user. Default actions are: `Update`, `Remove`, `Verify Email`.

<img src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/retool/users-managment-table.png?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=829f5d44f117233e0879bc691c2cd5c7" alt="Add REST API" data-og-width="3356" width="3356" data-og-height="1864" height="1864" data-path="images/retool/users-managment-table.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/retool/users-managment-table.png?w=280&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=5596a021c84ef8cd94d6767b384d7f7d 280w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/retool/users-managment-table.png?w=560&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=f6cd235d3d260858ff6978bac4a3d7ba 560w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/retool/users-managment-table.png?w=840&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=cfbf8deaccc871ed39cff70b0e19be2a 840w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/retool/users-managment-table.png?w=1100&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=a1c33590044f94bfff0a54d598a2ef13 1100w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/retool/users-managment-table.png?w=1650&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=02898152de8e69d4ff728b3330f4e1ec 1650w, https://mintcdn.com/ship/NJ8GmOFvTnU_w738/images/retool/users-managment-table.png?w=2500&fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=ae53ed85fa2e02d82ff4355f4eec0774 2500w" />

## App Resources

This section helps you to connect the resources that are used by predefined Retool apps.

### REST API

To connect [**API**](/api-reference/overview) service:

1. Select `REST API` resource
2. Give a name to the resource
3. Write `Base URL` of your server. For local development you need to [tunnel the traffic](#tunnel-http-traffic).
4. Add `x-admin-key` header. The value for `x-admin-key` is stored in config environments as `adminKey`.

<video controls className="w-full aspect-video" src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/video/retool/resources-add-rest-api.mp4?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=736d045872cc85de059cc6f66d0079ba" data-path="video/retool/resources-add-rest-api.mp4" />

### MongoDB

To connect **MongoDB** service:

1. Select `MongoDB` resource
2. Give a name to the resource
3. Select `Use a database connection string`. For local development you need to [tunnel the traffic](#tunnel-mongo-traffic).
4. Write `Connection String` of your database.  The value for `Connection String` is stored in config environments as `mongo.connection`.

<video controls className="w-full aspect-video" src="https://mintcdn.com/ship/NJ8GmOFvTnU_w738/video/retool/resources-add-mongodb.mp4?fit=max&auto=format&n=NJ8GmOFvTnU_w738&q=85&s=2edf868fd7994790cb1d173a7d2382bf" data-path="video/retool/resources-add-mongodb.mp4" />

<Tip>
  Learn how to use production and staging environments with Retool [documentation](https://docs.retool.com/docs/using-multiple-environments#configure-environment-resources).
</Tip>

## Local development

For some of [App Resources](#app-resources) will need to tunnel your local traffic.

### Tunnel http traffic

1. Install [ngrok](https://ngrok.com/)
2. Run `ngrok http <your-api-port>`

Link example:
`https://617c-93-125-14-163.ngrok.io`

### Tunnel mongo traffic

1. Install [ngrok](https://ngrok.com/)
2. Run `ngrok tcp <your-mongodb-port>`. You will see the forwarding link, for example `tcp:/2.tcp.ngrok.io:19888`.
3. Paste generated route to `mongodb://root:root@<generated-route>:19888/api-development?authSource=admin&replicaSet=rs&directConnection=true` link.

Link example:
`mongodb://root:root@2.tcp.ngrok.io:19888/api-development?authSource=admin&replicaSet=rs&directConnection=true`


# Scheduler
Source: https://ship.paralect.com/docs/scheduler



Sometimes building web applications, you meet repetitive tasks that should be run at a specific time every day, month, or year.
Some of these tasks may include:

* Sending periodic emails to customers;
* Backing up the organization’s data;
* Clearing logs from databases;

Here is where **Scheduler** comes in. It allows you to schedule jobs (arbitrary functions) for execution at specific dates, with optional recurrence rules.
Scheduler service shares the same code base with **[API](/api-reference/overview)** and located in the [`scheduler`](https://github.com/paralect/ship/tree/main/template/apps/api/src/scheduler) folder.

It runs and deploys as a standalone service with its own Dockerfile. This workflow allows time-consuming tasks not to interfere with the server processing requests.

Scheduler consists of two parts: [Cron jobs](#cron-jobs) and [Handlers](#handlers).

## Cron jobs

```typescript  theme={null}
import schedule from 'node-schedule';
import { EventEmitter } from 'events';

const eventEmitter = new EventEmitter();

schedule.scheduleJob('* * * * *', () => {
  eventEmitter.emit('cron:every-hour');
});

export default eventEmitter;
```

The cron jobs part is responsible for waiting some moment and emitting more specific events. It uses a [node-schedule](https://www.npmjs.com/package/node-schedule) library. In short, you should create a cron job in the appropriate format and emit an event using [EventEmitter](https://nodejs.dev/en/learn/the-nodejs-event-emitter/) that will be handled in the [Handlers](#handlers) part forward.

**Cron format**

<img src="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cron-format.png?fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=9b510390b6692e294c2b7d3b1d72f7da" alt="Cron format" data-og-width="1390" width="1390" data-og-height="383" height="383" data-path="images/cron-format.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cron-format.png?w=280&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=f489c26feec97a416658daf59d43a3e9 280w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cron-format.png?w=560&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=ad5441bac9239efc78d7568109083bd9 560w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cron-format.png?w=840&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b46c6d0361dc3f84db2a14f9fd08bf2d 840w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cron-format.png?w=1100&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=b6ffee755fe873b10f9b39abf6f0a72c 1100w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cron-format.png?w=1650&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=62e71baadfb33eddd26e0e70f23c88b9 1650w, https://mintcdn.com/ship/x4usuONuzojy0ONL/images/cron-format.png?w=2500&fit=max&auto=format&n=x4usuONuzojy0ONL&q=85&s=4de5b7d2cbf4b5978b4e375047191336 2500w" />

## Handlers

```typescript  theme={null}
import cron from 'scheduler/cron';

cron.on('cron:every-hour', async () => {
  try {
    const users = await userService.find({
      'scheduledEmail.deliveryDate': { $lte: new Date() },
    });

    users.map((u) => emailService.sendSignupWelcome(u.email))
  } catch (err) {
    console.log(`cron:every-hour error: ${err}`);
  }
});
```

The handlers part is responsible for listening to events from Cron jobs and running some handlers. Wrap handlers with try/catch to prevent a server from stopping or rebooting and create error logs.


# Calling API
Source: https://ship.paralect.com/docs/web/calling-api



## Overview

Ship uses [TanStack Query](https://tanstack.com/query/latest) with our own axios library wrapper.
All queries are located in the `/resources` folder, organized into sub-folders for each resource.

TanStack Query helps easily fetch, cache, and update data.
Each API endpoint has a related React hook using TanStack Query.

When getting data with **apiService** in `services/api.service.ts`, no need to add the full endpoint URL.
The axios instance already has the base URL set.

If you need to make a request to a new endpoint, for example, for a `project` resource,
you need to add a new hook to `/resources/project/project.api.ts`

## Examples

```typescript resources/account/account.api.ts theme={null}
export function useUpdate<T>() {
  const update = (data: T) => apiService.put("/account", data);

  return useMutation<User, unknown, T>(update);
}
```

```typescript resources/user/user.api.ts theme={null}
export function useList<T>(params: T) {
  const list = () => apiService.get("/users", params);

  interface UserListResponse {
    count: number;
    items: User[];
    totalPages: number;
  }

  return useQuery<UserListResponse>(["users", params], list);
}
```

```typescript pages/profile/index.page.tsx theme={null}
type UpdateParams = z.infer<typeof accountUpdateSchema>;

const { mutate: update, isLoading: isUpdateLoading } = accountApi.useUpdate<UpdateParams>();
```

```typescript pages/home/index.tsx theme={null}
const { data: users, isLoading: isUsersLoading } = userApi.useList(params);
```


# Environment Variables
Source: https://ship.paralect.com/docs/web/environment-variables



## Overview

We use different environment variables for different stages like developing, testing, and when the app is live.

This is done by using special files that have environments in them.

### How the App Chooses the Right Environment Variables File

The app knows which file to use based on a special environment variable called `APP_ENV`.

If `APP_ENV` is set to **staging**, the app will use the variables from the staging file.

<Card title="Development Stage" icon="code" iconType="light" color="#F96F5D">
  In this stage, we work on making the app and adding new things.

  The app uses a file named `.env.development` which has special environment variables just for people who are building the app.
</Card>

<Card title="Testing Stage (Staging)" icon="bug" iconType="light" color="#ca8b04">
  Here, we test the app to make sure it's ready to go live.

  We use the `.env.staging` file which has variables that help us test everything properly.
</Card>

<Card title="Live Stage (Production)" icon="industry-windows" iconType="light" color="#02C39A">
  In the Production, the app is all done and people can use it.

  App uses a file named `.env.production` which has environment variables for the app when it's being used by everyone.
</Card>

### Environment Variables Schema Validation

We use [Zod](https://zod.dev/) to check that our config is correct and in the right format.
This is important to make sure the app works without any problems.

This setup is found in the `src/config/index.ts` file.

<Tip>
  To prefix any variables intended for client-side exposure with `NEXT_PUBLIC_`.
</Tip>

When we add new environment variables to .env files, we need to make sure they match what we set up in the `Zod` schema.

## Adding a New Variable

Here's how to add a new environment variable to the application:

<Steps>
  <Step title="Identify the Environment Stages">
    Determine the environment stages where the new variable will be used.

    Refer to the following table for file associations:

    | APP\_ENV    | File             |
    | ----------- | ---------------- |
    | development | .env.development |
    | staging     | .env.staging     |
    | production  | .env.production  |
  </Step>

  <Step title="Update `.env` Files">
    Add the new variable to the respective `.env` files. For client-side variables, prefix them with `NEXT_PUBLIC_`.

    ```bash  theme={null}
    NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_TYooMQauvdEDq54NiTphI7jx
    ```
  </Step>

  <Step title="Modify the Schema in `src/config/index.ts`">
    Update the schema in the `config/index.ts` file to include the new variable.
    This step is crucial for schema validation.

    ```typescript config/index.ts theme={null}
    const schema = z.object({
        ...
        STRIPE_PUBLISHABLE_KEY: z.string(),
    });
    ```
  </Step>

  <Step title="Update the Configuration Object">
    Add the new variable to the configuration object within the same file (`config/index.ts`), ensuring it matches the schema.

    ```typescript config/index.ts theme={null}
    const processEnv = {
        ...
        STRIPE_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY,
    };
    ```
  </Step>
</Steps>

<Warning>
  All the environment variables we use in the front-end part of our app can be seen by everyone.
  So, don't put any secret stuff like passwords or private keys there.

  Keep those safe and only on the server side! 🛡️✨
</Warning>


# Forms
Source: https://ship.paralect.com/docs/web/forms



## Overview

We use the [react-hook-form](https://react-hook-form.com/) library along with [@hookform/resolvers](https://www.npmjs.com/package/@hookform/resolvers) to simplify the process of creating and managing forms.
This setup allows for the quick development of robust forms.

### Form Schema

With [@hookform/resolvers](https://www.npmjs.com/package/@hookform/resolvers), you can validate your forms using a Zod schema.
Just write the schema and use it as a resolver in the `useForm` hook.
This approach not only validates your forms but also helps in creating perfectly typed forms by inferring types from the schema.

Example of setting up a form with Zod schema:

```tsx  theme={null}
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// Define your schema
const schema = z.object({
  firstName: z.string().min(1, 'Please enter First name').max(100),
  lastName: z.string().min(1, 'Please enter Last name').max(100),
  email: z.string().regex(EMAIL_REGEX, 'Email format is incorrect.'),
});

// Infer type from schema
type FormParams = z.infer<typeof schema>;

const Page = () => {
  const { register, handleSubmit } = useForm<FormParams>({
    resolver: zodResolver(schema),
  });

  // Form handling code here
};
```

### Error Handling

For error handling in forms, we use the `handle-error.util.ts` utility function.
This function parses error messages, sets them to the form fields' error states, or displays a global notification for general errors.

Usage:

```tsx  theme={null}
import { useForm } from 'react-hook-form';
import { handleError } from 'utils';

const Page: NextPage = () => {
  const { setError } = useForm();

  // Submit function
  const onSubmit = (data: SignUpParams) => signUp(data, {
    onError: (e) => handleError(e, setError),
  });
}
```

#### Form usage

Here is an example of how you can create a form:

```tsx  theme={null}
import { handleError } from 'utils';
import { accountApi } from 'resources/account';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

// Define your schema
const schema = z.object({
  // Schema details here
});

// Infer type from schema
type SignUpParams = z.infer<typeof schema>;

const Page: NextPage = () => {
  const { mutate: signUp, isLoading: isSignUpLoading } = accountApi.useSignUp();
  const {
    register,
    handleSubmit,
    setError,
    formState: { errors },
  } = useForm<SignUpParams>({
    resolver: zodResolver(schema),
  });

  // Submit function
  const onSubmit = (data: SignUpParams) => signUp(data, {
    onSuccess: (data) => {
      // Handle success response
      queryClient.setQueryData(['account'], data);
    },
    onError: (e) => handleError(e, setError),
  });

  // Form rendering
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <TextInput
        {...register('name')}
        error={errors.name?.message}
      />

      <Button
        type="submit"
        loading={isSignUpLoading}
      >
        Submit
      </Button>
    </form>
  );
};
```

By following these guidelines, you can effectively build and manage forms in our application,
ensuring a smooth user experience and robust form handling.


# Overview
Source: https://ship.paralect.com/docs/web/overview



Web Starter is our starting point for React front-end applications.
It's crafted using a selection of advanced technologies and tools, making it a robust and efficient foundation for development.

The core technologies include:

* [Next.js](https://nextjs.org/): A React framework that supports features like server-side rendering, static site generation and routing.
* [TanStack Query](https://tanstack.com/query): A library for managing data fetching, caching, and updating in React apps.
* [React Hook Form](https://react-hook-form.com/) + [Zod](https://zod.dev/): Efficient form management and schema validation tools.
* [Mantine UI](https://mantine.dev/) + [Tabler](https://tabler-icons.io/): UI components and icons for responsive and accessible web interfaces.
* [Typescript](https://www.typescriptlang.org/): JavaScript with syntax for types, enhancing scalability and maintainability.

## Web Starter Documentation Sections

Explore the following sections for detailed information on different aspects of the Web Starter:

* [Styling](/web/styling): Focuses on the styling approach used in the application, detailing how to work with Mantine UI to create visually appealing interfaces.
* [Routing](/web/routing): Covers the routing mechanism within the application, explaining how to organize navigation flow.
* [Calling API](/web/calling-api): Dedicated to API interactions, this section explains how to effectively make requests to back-end services, manage responses, and handle errors using the provided API service utilities.
* [Forms](/web/forms): Discusses form management, highlighting the integration of React Hook Form and Zod for efficient form creation, validation, and handling user inputs.
* [Services](/web/services): Describes the various service layers used in the application, such as the API, socket, and analytics services, providing examples of how to implement and utilize these services for different functionalities.
* [Environment Variables](/web/environment-variables): Guides on managing environment-specific configurations, explaining the use of different `.env` files for development, staging, and production environments, and the importance of securing sensitive data.

## React TypeScript Cheatsheet

For a detailed guide on using React with TypeScript,
visit the [React TypeScript Cheatsheet](https://react-typescript-cheatsheet.netlify.app/docs/basic/setup/).


# Routing
Source: https://ship.paralect.com/docs/web/routing



Our application's routing is powered by [Next.js Pages router](https://nextjs.org/docs/pages), which is a standard for handling routes in Next.js applications.

## Configuration in `routes.ts`

Each route in our application is configured in the `routes.ts` file, located in the root of the `routes` directory.
This file defines the structure and access levels of all routes using the `routesConfiguration` object.

### Scope and Layout Types

Routes are categorized into two scope types and layout types:

1. **Scope Types**:

* `PUBLIC`: Routes accessible without user authentication.
* `PRIVATE`: Routes requiring user authentication.

2. **Layout Types**:

* `MAIN`: Main layout for authenticated users.
* `UNAUTHORIZED`: Layout for non-authenticated users or authentication pages.

### Route Configuration Example

Here's an example of how a private and a public route are configured:

* Private Route (Requires authentication):

```tsx src/routes.ts theme={null}
[RoutePath.Profile]: {
  scope: ScopeType.PRIVATE,
  layout: LayoutType.MAIN,
}
```

* Public Route (Accessible without authentication):

```tsx src/routes.ts theme={null}
[RoutePath.ForgotPassword]: {
  scope: ScopeType.PUBLIC,
  layout: LayoutType.UNAUTHORIZED,
},
```

## Page Configuration

The PageConfig (`/pages/_app/PageConfig/index.tsx` file) plays a crucial role in applying these configurations.
It uses the route configuration from `routes.ts` to determine the appropriate scope and layout for each page.

### How It Works

* The `PageConfig` component, using the Next.js router, matches the current route against the `routesConfiguration`.
* Based on the route, it applies the designated scope and layout.
* For private routes, it redirects unauthenticated users to the sign-in page.
* Conversely, for public routes, authenticated users are redirected to the home page.

## Naming Conventions for Route Files

* **Page Routes**: Each file representing a page route should have the `.page.tsx` postfix.
* **API Routes/Middleware**: Files for Next.js API routes or middleware should have the `.api.ts` postfix.

<Note>
  These conventions can be modified in `next.config.js` if needed.
</Note>

By following this structure, our application maintains a clear, manageable, and scalable routing system.


# Services
Source: https://ship.paralect.com/docs/web/services



## Overview

Services in our application are specific functionalities or data manipulations handled by objects, classes, or functions.
You can add any service as needed for third-party API integrations or app metrics collection.

### API Service

**Description:**
The API Service, represented by the `ApiClient` class, enhances axios client for better error handling and easier configuration.

**Example Usage:**

```typescript  theme={null}
import { apiService } from 'services';

// Making a GET request
const data = await apiService.get('/users', { sort: { createdOn: 'desc' } });
```

### Socket Service

**Description:**
Socket Service provides functions for managing websocket connections, including connecting, disconnecting, and handling events.

**Example Usage:**

```tsx  theme={null}
import { socketService } from 'services';

// Listening for an event
socketService.on('user:updated', (data: User) => {
  queryClient.setQueryData(['account'], data);
});

// In React component
const onCardUpdated = () => {
  console.log('Card updated')
};

useEffect(() => {
  socketService.on('card:updated', onCardUpdated);

  return () => {
    socketService.off('card:updated', onCardUpdated);
  };
}, []);
```

### Analytics Service

**Description:**
Analytics Service offers a set of functionalities for working with third-party analytics systems like Mixpanel. It can be adapted to other platforms as needed.

**Example Usage:**

```typescript  theme={null}
import { analyticsService } from 'services';

// Tracking an event
analyticsService.track('New user created', { firstName, lastName });
```


# Storybook
Source: https://ship.paralect.com/docs/web/storybook



Storybook is powerful tool for developing, testing, and reviewing UI components in isolation.
Chromatic helps you to automate the process of reviewing UI changes.

Follow the official guides below to add them to your project.

## Official Setup Guides

* [Setup Mantine in Storybook Guide](https://mantine.dev/guides/storybook/)
* [Chromatic GitHub Actions Guide](https://www.chromatic.com/docs/github-actions/)

## Project Conventions

* **Stories Organization:**
  * Application components: `src/components`
  * UI Kit (theme components): `src/theme/components`
* **Storybook stories path config:**

```tsx .storybook/main.ts theme={null}
stories: [
  {
    directory: '../src/components',
    titlePrefix: 'Application Components',
  },
  {
    directory: '../src/theme/components',
    titlePrefix: 'UI Kit',
  },
],
```

## Example: Mantine Button Story

```tsx src/theme/components/Button/index.stories.tsx theme={null}
import { Button, ButtonProps } from '@mantine/core';
import type { Meta, StoryObj } from '@storybook/react';

const meta = {
  component: Button,
  args: {
    children: 'Button',
    variant: 'primary',
    size: 'md',
    loading: false,
  },
  argTypes: {
    variant: {
      options: ['primary', 'outline'],
      control: { type: 'radio' },
    },
    size: {
      options: ['md', 'lg'],
      control: { type: 'radio' },
    },
    loading: {
      control: { type: 'boolean' },
    },
  },
} satisfies Meta<typeof Button>;

export default meta;

type Story = StoryObj<ButtonProps>;

export const Basic: Story = {};
```


# Styling
Source: https://ship.paralect.com/docs/web/styling



Ship aims for efficiency and convenience in styling by leveraging the [Mantine UI](https://v6.mantine.dev/) library.
Mantine UI offers a wide range of customizable components and hooks that facilitate the creation of visually appealing and functional interfaces.

### Theme Configuration (`theme/index.ts`)

Our application's design system is built on top of Mantine's [theme object](https://v6.mantine.dev/theming/theme-object/).
The theme object allows us to define global style properties that can be applied consistently across web application.

### Custom Components (`components/index.js`)

We extend Mantine's components to create custom-styled versions specific to our application needs.

Here's an example of how we extend the Mantine `Button` component:

* We set the default button size to 'large' (`lg`).

```typescript theme/components/index.ts theme={null}
import { Button } from '@mantine/core';

import classes from './index.module.css';

export default Button.extend({
  defaultProps: {
    size: 'lg',
  },
  classNames: {
    label: classes.label,
  },
});
```

* Custom class names are applied for additional styling, defined in our `index.module.css`.

```typescript theme/components/index.ts theme={null}
.label {
  font-weight: 500;
}
```