Skip to content

Commit 4c5d119

Browse files
adar-sshadar-ssh
committed
DevOps documentation
1 parent 95250a8 commit 4c5d119

2 files changed

Lines changed: 209 additions & 17 deletions

File tree

‎.env.example‎

Lines changed: 0 additions & 17 deletions
This file was deleted.

‎DEVOPS.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# DevOps & Deployment Guide
2+
3+
This document outlines the DevOps practices, build processes, and deployment strategies for the **Form Engine Backend** project.
4+
5+
## 1. Technology Stack
6+
7+
- **Runtime**: [Bun](https://bun.sh/)
8+
- **Framework**: [ElysiaJS](https://elysiajs.com/)
9+
- **Language**: [TypeScript](https://www.typescriptlang.org/)
10+
- **Database**: [PostgreSQL](https://www.postgresql.org/)
11+
- **ORM**: [Prisma](https://www.prisma.io/)
12+
- **Auth**: [Better Auth](https://www.better-auth.com/)
13+
- **Logging**: [Pino](https://github.com/pinojs/pino)
14+
- **Testing**: [Bun Test](https://bun.sh/docs/cli/test)
15+
- **Linting**: [Biome](https://biomejs.dev/)
16+
- **API Client**: [Bruno](https://www.usebruno.com/)
17+
18+
## 2. Local Development Setup
19+
20+
### Prerequisites
21+
- **Node.js**: v18+ (Recommended for some tools)
22+
- **Bun**: Latest version (`curl -fsSL https://bun.sh/install | bash`)
23+
- **Docker**: For running the database locally.
24+
25+
### Installation
26+
Clone the repository and install dependencies using Bun:
27+
```bash
28+
git clone <repository-url>
29+
cd form-engine-backend
30+
bun install
31+
```
32+
33+
### Database Setup
34+
Start the PostgreSQL database using Docker Compose:
35+
```bash
36+
docker-compose up -d
37+
```
38+
Generate the Prisma client:
39+
```bash
40+
bunx prisma generate
41+
```
42+
43+
### Running the Dev Server
44+
The server will start on port `8000`.
45+
```bash
46+
bun run dev
47+
```
48+
49+
## 3. Code Quality & Testing
50+
51+
Ensure code quality before pushing changes.
52+
53+
### Linting & Formatting
54+
Used Biome for both linting and formatting.
55+
```bash
56+
# Check for linting/formatting errors
57+
bun run check
58+
59+
# Fix auto-fixable issues
60+
bunx biome check --write
61+
```
62+
63+
### Type Checking
64+
TypeScript validation:
65+
```bash
66+
bun run typecheck
67+
```
68+
69+
### Testing
70+
Run unit tests via Bun Test:
71+
```bash
72+
# Run tests
73+
# Run tests (Coverage enabled by default in bunfig.toml)
74+
bun test
75+
```
76+
77+
### API Documentation & Testing
78+
The project uses [Bruno](https://www.usebruno.com/) for API documentation and testing.
79+
- Collections are located in the `./bruno` directory.
80+
- Open the `./bruno` folder in the Bruno app to view and run API requests.
81+
82+
## 4. Build Process
83+
84+
The project is built using Bun's bundler, targeting the Bun runtime.
85+
86+
```bash
87+
bun run build
88+
```
89+
**Output**:
90+
- Directory: `./dist`
91+
- Artifact: `dist/index.js`
92+
- Target: Bun (minified)
93+
94+
## 5. Containerization (Docker)
95+
96+
To containerize the application for deployment (e.g., for Kubernetes or Cloud Run), use the following configuration.
97+
98+
### Recommended `Dockerfile`
99+
Create a file named `Dockerfile` in the root:
100+
101+
```dockerfile
102+
FROM oven/bun:1 AS base
103+
WORKDIR /app
104+
105+
# install dependencies into temp directory
106+
# this will cache them and speed up future builds
107+
FROM base AS install
108+
RUN mkdir -p /temp/dev
109+
COPY package.json bun.lock /temp/dev/
110+
RUN cd /temp/dev && bun install --frozen-lockfile
111+
112+
RUN mkdir -p /temp/prod
113+
COPY package.json bun.lock /temp/prod/
114+
RUN cd /temp/prod && bun install --frozen-lockfile --production
115+
116+
# copy node_modules from temp directory
117+
# then copy all (non-ignored) project files into the image
118+
FROM base AS prerelease
119+
COPY --from=install /temp/dev/node_modules node_modules
120+
COPY . .
121+
122+
# [optional] tests & build
123+
ENV NODE_ENV=production
124+
RUN bun test
125+
RUN bun run build
126+
127+
# copy production dependencies and source code into final image
128+
FROM base AS release
129+
COPY --from=install /temp/prod/node_modules node_modules
130+
COPY --from=prerelease /app/dist/index.js index.js
131+
COPY --from=prerelease /app/package.json package.json
132+
133+
# run the app
134+
USER bun
135+
EXPOSE 8000/tcp
136+
ENTRYPOINT [ "bun", "run", "index.js" ]
137+
```
138+
139+
### Recommended `.dockerignore`
140+
```text
141+
node_modules
142+
dist
143+
.git
144+
.env
145+
```
146+
147+
## 6. CI/CD Strategy
148+
149+
We use GitHub Actions to validate code on every Pull Request.
150+
151+
### GitHub Actions Workflow
152+
The workflow is defined in `.github/workflows/backend-ci.yml`.
153+
154+
**Key Steps:**
155+
1. **Checkout code**: Pulls the code from the repository.
156+
2. **Setup Bun**: Installs the Bun runtime.
157+
3. **Cache dependencies**: Caches `node_modules` and database-related artifacts to speed up builds.
158+
4. **Install dependencies**: `bun install`.
159+
5. **Generate Prisma client**: Generates the type-safe database client.
160+
6. **Code quality check**: Runs `bun run check` (Biome).
161+
7. **Type checking**: Runs `bun run typecheck`.
162+
8. **Run database migrations**: Applies Prisma migrations to the test database.
163+
9. **Security audit**: Runs `bun audit`.
164+
10. **Build application**: Runs `bun run build`.
165+
11. **Build verification**: Ensures the built artifact can start.
166+
12. **Upload artifacts**: Saves the `dist` directory.
167+
168+
## 7. DevOps Strategy Overview
169+
170+
The following diagram illustrates the automated DevOps pipeline from code commit to deployment.
171+
172+
```mermaid
173+
graph TD
174+
A[Code Commit] -->|Push to Main| B(CI Pipeline)
175+
B --> C{Checks Pass?}
176+
C -->|No| D[Notify Developer]
177+
C -->|Yes| E[Build Application]
178+
E --> F[Create Docker Image]
179+
F --> G[Push to Registry]
180+
G --> H[Deploy to Target Env]
181+
```
182+
183+
## 8. Component Deployment Strategy
184+
185+
This section details the source, deployment target, and validation checks for each major component.
186+
187+
### Backend API (`form-engine-backend`)
188+
189+
| Attribute | Description |
190+
| :--- | :--- |
191+
| **Source Code Repo** | `form-engine-backend` (Git) |
192+
| **Deployment Location** | Docker Container in Kubernetes / Cloud Run / VPS |
193+
| **Tools & Platforms** | **Docker** (Containerization), **GitHub Actions** (CI/CD), **Bun** (Runtime) |
194+
| **Pre-Deployment Checks** | 1. **Linting**: `bun run check`<br>2. **Type Checking**: `bun run typecheck`<br>3. **Unit Tests**: `bun test`<br>4. **Security Audit**: `bun audit`<br>5. **Build Verification**: `bun run build` |
195+
196+
### Database (`PostgreSQL`)
197+
198+
| Attribute | Description |
199+
| :--- | :--- |
200+
| **Source Definition** | `prisma/schema.prisma` in `form-engine-backend` Repo |
201+
| **Deployment Location** | Managed PostgreSQL Service (e.g., AWS RDS, Supabase) or StatefulSet |
202+
| **Tools & Platforms** | **Prisma** (ORM & Migrations), **PostgreSQL 17** (Database Docker Image) |
203+
| **Pre-Deployment Checks** | 1. **Schema Validation**: `bunx prisma validate`<br>2. **Migration Status**: `bunx prisma migrate status`<br>3. **Migration Apply**: `bunx prisma migrate deploy` (during deployment) |
204+
205+
## 9. Tools & Ecosystem
206+
207+
The following tools and libraries are standardized for this project's DevOps lifecycle:
208+
209+
- **Source Control**: [GitHub](https://github.com/Nandgopal-R/form-engine)

0 commit comments

Comments
 (0)