How to Set Up a Development Environment for oblien/openship: A Complete Guide

Clone the repository, install Node.js 20+ and pnpm, copy .env.example to .env, run pnpm install, start the Docker Compose stack with docker compose -f docker/docker-compose.yml up -d, and launch individual services using pnpm --filter commands.

The oblien/openship repository is a TypeScript-based monorepo that orchestrates multi-cloud deployments through a unified interface. Setting up a development environment for oblien/openship requires configuring pnpm workspaces, Docker containers for PostgreSQL and Redis, and environment variables defined in .env.example. This guide walks through the exact steps to configure your local machine based on the project's actual source structure and dependencies.

Prerequisites and System Requirements

Before cloning the repository, ensure your system meets the following specifications defined in the source configuration:

• Node.js ≥20 – The version is pinned in .nvmrc at the repository root. Use a version manager like nvm to match this exactly.
• pnpm – The package manager for the workspace. Install globally with npm i -g pnpm.
• Docker & Docker Compose – Required to run the PostgreSQL database, Redis cache, and API services locally.

Repository Architecture Overview

Understanding the workspace structure helps navigate the development environment. The project uses pnpm-workspace.yaml to define package boundaries across multiple logical layers:

• apps/web – Vite-based React frontend with Tailwind CSS, accessible at http://localhost:3000
• apps/api – Fastify server exposing the public API at http://localhost:4000
• apps/desktop – Electron-based desktop client sharing UI components with the web app
• packages/db – Prisma schema and database migration scripts
• packages/adapters – Plugin system for cloud providers (AWS, GCP, Azure)
• packages/core – Shared TypeScript types and service-layer abstractions

Step-by-Step Development Environment Setup

1. Clone the Repository and Install Dependencies

Start by cloning the repository and installing workspace dependencies:

git clone https://github.com/oblien/openship.git
cd openship
pnpm install

The pnpm install command reads pnpm-workspace.yaml and creates a single pnpm-lock.yaml file while maintaining isolated node_modules for each package.

2. Configure Environment Variables

Copy the example environment file and customize it with your credentials:

cp .env.example .env

The .env.example file contains placeholders for database URLs, cloud provider API keys, and service ports. Fill in any required credentials for the cloud adapters you plan to develop against.

3. Start the Docker Infrastructure

Launch the backing services defined in docker/docker-compose.yml:

docker compose -f docker/docker-compose.yml up -d

This command starts:

• PostgreSQL – Primary database for the Prisma schema
• Redis – Caching layer for the API
• API prerequisites – Network configurations shared with the Fastify server

4. Initialize the Database

Run Prisma migrations to set up the database schema:

pnpm --filter @openship/db migrate dev

Running Development Services

The monorepo uses pnpm --filter commands to target specific packages. Each service runs independently, allowing you to develop specific components without starting the entire stack.

Web UI (Vite Development Server)

Start the React frontend with hot-module replacement:

pnpm --filter @openship/web dev

The Vite dev server binds to http://localhost:3000. The entry point at apps/web/src/main.tsx bootstraps the React application:

// apps/web/src/main.tsx
import { createRoot } from 'react-dom/client';
import { App } from './App';

const container = document.getElementById('root')!;
createRoot(container).render(<App />);

To configure API communication, the web app uses environment variables pointing to the local Fastify server:

// apps/web/src/lib/api.ts
import axios from 'axios';

export const client = axios.create({
  baseURL: import.meta.env.VITE_API_URL ?? 'http://localhost:4000',
  timeout: 10_000,
});

export async function fetchProjects() {
  const { data } = await client.get('/projects');
  return data;
}

API Server (Fastify)

Start the backend service with:

pnpm --filter @openship/api dev

The Fastify server entry point at apps/api/src/server.ts initializes the HTTP listener on port 4000:

// apps/api/src/server.ts
import Fastify from 'fastify';
import { registerRoutes } from './routes';

export const server = Fastify({ logger: true });

registerRoutes(server);

server.listen({ port: 4000, host: '0.0.0.0' });

Desktop Application (Electron)

Run the Electron client using:

pnpm --filter @openship/desktop dev

The desktop app imports the same React components as the web UI but wraps them in a native Electron shell defined in apps/desktop/src/main.ts.

Testing and Code Quality

The repository uses Vitest for unit testing and ESLint with Prettier for code quality.

Run all tests across the workspace:

pnpm test

Target a specific package:

pnpm --filter @openship/db test

Lint and format the codebase:

pnpm lint
pnpm format

Extending the Platform: Adding Custom Adapters

To add a new cloud provider adapter, create a package within packages/adapters/src/providers/:

# Create a new provider directory

mkdir packages/adapters/src/providers/mock

Implement the CloudAdapter interface:

// packages/adapters/src/providers/mock/index.ts
import { CloudAdapter } from '../../types';

export class MockAdapter implements CloudAdapter {
  async listBuckets() {
    return [{ name: 'demo-bucket', region: 'us-east-1' }];
  }
}

Building for Production

Create production bundles for deployment:

# Static web bundle

pnpm --filter @openship/web build

# API compilation

pnpm --filter @openship/api build

# Desktop binaries

pnpm --filter @openship/desktop build

Summary

• Clone the oblien/openship repository and ensure Node.js 20+ and pnpm are installed.
• Copy .env.example to .env and configure your cloud provider credentials and database URLs.
• Start the Docker Compose stack from docker/docker-compose.yml to run PostgreSQL and Redis.
• Install dependencies with pnpm install, which respects the pnpm-workspace.yaml configuration.
• Launch individual services using pnpm --filter @openship/web dev, pnpm --filter @openship/api dev, or pnpm --filter @openship/desktop dev.
• Test changes using pnpm test and validate code quality with pnpm lint.

Frequently Asked Questions

What Node.js version is required for oblien/openship?

The repository requires Node.js 20 or higher, as specified in the .nvmrc file at the repository root. Using a version manager like nvm ensures compatibility with the TypeScript build tools and pnpm workspaces.

Can I use npm or yarn instead of pnpm?

No. The oblien/openship monorepo relies on pnpm workspaces defined in pnpm-workspace.yaml for dependency hoisting and isolated package management. The workspace scripts in the root package.json assume pnpm-specific commands and filtering syntax.

Is Docker mandatory for local development?

Yes. The Fastify API depends on PostgreSQL and Redis instances defined in docker/docker-compose.yml. While you can run the web UI (@openship/web) independently using mock data, full integration development requires the Docker stack to handle database migrations and API requests.

How do I add environment variables for new cloud providers?

Add your provider-specific keys to the .env file you created from .env.example. The packages/adapters modules read these variables during initialization. Refer to docs/installation.md for provider-specific configuration requirements and ensure you restart the API server after modifying environment variables.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}