Skip to content

docs: updates for PR #3868 #3878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
dosubot wants to merge 1 commit into from
+234 −0
Closed

docs: updates for PR #3868 #3878

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 234 additions & 0 deletions apps/api/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,237 @@ npm run dev
```
open http://localhost:3000
```

## Environment Variables

The API server requires the following environment variables for configuration:

### Inngest Configuration

Required for the GET /jobs endpoint to list deployment jobs:

- **INNGEST_BASE_URL** - The base URL for the Inngest instance
- Self-hosted: `http://localhost:8288`
- Production: `https://dev-inngest.dokploy.com`

- **INNGEST_SIGNING_KEY** - The signing key for authenticating with Inngest

Optional configuration for filtering and pagination:

- **INNGEST_EVENTS_RECEIVED_AFTER** (optional) - An RFC3339 timestamp to filter events received after a specific date (e.g., `2024-01-01T00:00:00Z`). If unset, no date filter is applied.
Copy link
Contributor

@greptile-apps greptile-apps bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

INNGEST_EVENTS_RECEIVED_AFTER is not implemented. The environment variable is never read in the codebase, and fetchInngestEvents() in service.ts constructs its query with only limit and cursor — there is no date filtering capability. Documenting this implies users can configure this behavior, which is misleading.


- **INNGEST_JOBS_MAX_EVENTS** (optional) - Maximum number of events to fetch when listing jobs. Default is 100, maximum is 10000. Used for pagination with cursor.
Copy link
Contributor

@greptile-apps greptile-apps bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The INNGEST_JOBS_MAX_EVENTS variable is undocumented in the implementation. In service.ts, the maximum is hardcoded:

const DEFAULT_MAX_EVENTS = 500;
const MAX_EVENTS = DEFAULT_MAX_EVENTS;

The environment variable is never read. This means setting INNGEST_JOBS_MAX_EVENTS has no effect, and the actual default is 500 (not 100 as documented, and it's not configurable to a maximum of 10000).


### Lemon Squeezy Integration

- **LEMON_SQUEEZY_API_KEY** - API key for Lemon Squeezy integration
- **LEMON_SQUEEZY_STORE_ID** - Store ID for Lemon Squeezy integration
Comment on lines +10 to +33
Copy link
Contributor

@greptile-apps greptile-apps bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The API_KEY environment variable is missing from the documentation. However, index.ts enforces authentication via API_KEY for all routes except /health and /api/inngest:

const authHeader = c.req.header("X-API-Key");
if (process.env.API_KEY !== authHeader) {
  return c.json({ message: "Invalid API Key" }, 403);
}

This is a required environment variable — callers must send it as the X-API-Key header or protected endpoints return 403. It should be documented prominently in the environment variables section.


## API Endpoints

### GET /jobs

Lists deployment jobs (Inngest runs) for a specified server.

**Query Parameters:**
- `serverId` (required) - The ID of the server to list deployment jobs for

**Response:**
Returns an array of deployment job objects with the same shape as BullMQ queue jobs:
```json
[
{
"id": "string",
"name": "string",
"data": {},
"timestamp": 0,
"processedOn": 0,
"finishedOn": 0,
"failedReason": "string",
"state": "string"
}
]
```

**Error Responses:**
- `400` - serverId is not provided
- `503` - INNGEST_BASE_URL is not configured
- `200` - Empty array on other errors

This endpoint is used by the UI to display deployment queue information in the dashboard.

## Search Endpoints

The following search endpoints provide flexible querying capabilities with pagination support. All search endpoints respect member permissions, returning only resources the user has access to.

### application.search

Search applications across name, appName, description, repository, owner, and dockerImage fields.

**Query Parameters:**
- `q` (optional string) - General search term that searches across name, appName, description, repository, owner, and dockerImage
- `name` (optional string) - Filter by application name
- `appName` (optional string) - Filter by app name
- `description` (optional string) - Filter by description
- `repository` (optional string) - Filter by repository
- `owner` (optional string) - Filter by owner
- `dockerImage` (optional string) - Filter by Docker image
- `projectId` (optional string) - Filter by project ID
- `environmentId` (optional string) - Filter by environment ID
- `limit` (number, default 20, min 1, max 100) - Maximum number of results
- `offset` (number, default 0, min 0) - Pagination offset

**Response:**
```json
{
"items": [
{
"applicationId": "string",
"name": "string",
"appName": "string",
"description": "string",
"environmentId": "string",
"applicationStatus": "string",
"sourceType": "string",
"createdAt": "string"
}
],
"total": 0
}
```

### compose.search

Search compose services with filtering by name, appName, and description.

**Query Parameters:**
- `q` (optional string) - General search term across name, appName, description
- `name` (optional string) - Filter by name
- `appName` (optional string) - Filter by app name
- `description` (optional string) - Filter by description
- `projectId` (optional string) - Filter by project ID
- `environmentId` (optional string) - Filter by environment ID
- `limit` (number, default 20, min 1, max 100) - Maximum results
- `offset` (number, default 0, min 0) - Pagination offset

**Response:**
```json
{
"items": [
{
"composeId": "string",
"name": "string",
"appName": "string",
"description": "string",
"environmentId": "string",
"composeStatus": "string",
"sourceType": "string",
"createdAt": "string"
}
],
"total": 0
}
```

### environment.search

Search environments by name and description.

**Query Parameters:**
- `q` (optional string) - General search term across name and description
- `name` (optional string) - Filter by name
- `description` (optional string) - Filter by description
- `projectId` (optional string) - Filter by project ID
- `limit` (number, default 20, min 1, max 100) - Maximum results
- `offset` (number, default 0, min 0) - Pagination offset

**Response:**
```json
{
"items": [
{
"environmentId": "string",
"name": "string",
"description": "string",
"createdAt": "string",
"env": "string",
"projectId": "string",
"isDefault": true
}
],
"total": 0
}
```

### project.search

Search projects by name and description.

**Query Parameters:**
- `q` (optional string) - General search term across name and description
- `name` (optional string) - Filter by name
- `description` (optional string) - Filter by description
- `limit` (number, default 20, min 1, max 100) - Maximum results
- `offset` (number, default 0, min 0) - Pagination offset

**Response:**
```json
{
"items": [
{
"projectId": "string",
"name": "string",
"description": "string",
"createdAt": "string",
"organizationId": "string",
"env": "string"
}
],
"total": 0
}
```

### Database Service Search Endpoints

The following database services all share the same search interface:
- **postgres.search**
- **mysql.search**
- **mariadb.search**
- **mongo.search**
- **redis.search**

**Query Parameters:**
- `q` (optional string) - General search term across name, appName, description
- `name` (optional string) - Filter by name
- `appName` (optional string) - Filter by app name
- `description` (optional string) - Filter by description
- `projectId` (optional string) - Filter by project ID
- `environmentId` (optional string) - Filter by environment ID
- `limit` (number, default 20, min 1, max 100) - Maximum results
- `offset` (number, default 0, min 0) - Pagination offset

**Response:**
```json
{
"items": [
{
"postgresId": "string",
"name": "string",
"appName": "string",
"description": "string",
"environmentId": "string",
"applicationStatus": "string",
"createdAt": "string"
}
],
"total": 0
}
```

*Note: The response shape is similar across all database services, with the ID field varying (e.g., `mysqlId`, `mariadbId`, `mongoId`, `redisId`).*

**Search Behavior:**
- All searches use case-insensitive pattern matching with wildcards
- Results are ordered by creation date (descending)
- Members only see services they have access to
- Returns total count for pagination UI
Comment on lines +68 to +242
Copy link
Contributor

@greptile-apps greptile-apps bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Search Endpoints" section documents tRPC procedures that do not exist in this service. This apps/api package is a standalone Hono HTTP server that only exposes /deploy, /cancel-deployment, /health, /jobs, and /api/inngest.

The search endpoints (application.search, compose.search, environment.search, project.search, postgres.search, mysql.search, mariadb.search, mongo.search, redis.search) are tRPC procedures from the main application's API, not endpoints available in this standalone service.

This section should be removed from this README to avoid confusion.

Copy link
Contributor

@greptile-apps greptile-apps bot Mar 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add a trailing newline at the end of the file. The file currently ends without one.

Suggested change
- Returns total count for pagination UI
- Returns total count for pagination UI
\ No newline at end of file
+ Returns total count for pagination UI

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!