@cronicorn/mcp-server 1.19.0 → 1.19.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +87 -436
- package/dist/docs/api-reference.md +558 -0
- package/dist/docs/core-concepts.md +9 -1
- package/dist/docs/introduction.md +15 -5
- package/dist/docs/mcp-server.md +49 -69
- package/dist/docs/quick-start.md +11 -2
- package/dist/docs/self-hosting.md +10 -1
- package/dist/docs/technical/configuration-and-constraints.md +11 -2
- package/dist/docs/technical/coordinating-multiple-endpoints.md +11 -2
- package/dist/docs/technical/how-ai-adaptation-works.md +122 -385
- package/dist/docs/technical/how-scheduling-works.md +76 -2
- package/dist/docs/technical/reference.md +11 -2
- package/dist/docs/technical/system-architecture.md +57 -189
- package/dist/docs/troubleshooting.md +392 -0
- package/dist/docs/use-cases.md +10 -1
- package/package.json +1 -1
- package/dist/docs/competitive-analysis.md +0 -324
- package/dist/docs/developers/README.md +0 -29
- package/dist/docs/developers/authentication.md +0 -121
- package/dist/docs/developers/environment-configuration.md +0 -103
- package/dist/docs/developers/quality-checks.md +0 -68
- package/dist/docs/developers/quick-start.md +0 -87
- package/dist/docs/developers/workspace-structure.md +0 -174
|
@@ -1,324 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: competitive-analysis
|
|
3
|
-
title: How Cronicorn Compares
|
|
4
|
-
description: Understand how Cronicorn stacks up against other job scheduling platforms
|
|
5
|
-
sidebar_label: Competitive Analysis
|
|
6
|
-
sidebar_position: 5
|
|
7
|
-
tags:
|
|
8
|
-
- user
|
|
9
|
-
- comparison
|
|
10
|
-
- features
|
|
11
|
-
mcp:
|
|
12
|
-
uri: file:///docs/competitive-analysis.md
|
|
13
|
-
mimeType: text/markdown
|
|
14
|
-
priority: 0.7
|
|
15
|
-
lastModified: 2025-11-04T00:00:00Z
|
|
16
|
-
---
|
|
17
|
-
|
|
18
|
-
# How Cronicorn Compares to Other Job Schedulers
|
|
19
|
-
|
|
20
|
-
**TL;DR**: Cronicorn is the only platform that automatically adapts job schedules based on real-time performance. While others offer static cron or complex workflow orchestration, Cronicorn learns from your endpoints and optimizes timing automatically—all while staying within your safety constraints.
|
|
21
|
-
|
|
22
|
-
Cronicorn is purpose-built for **adaptive HTTP job scheduling**—a unique position in the workflow automation landscape. Here's how we compare to popular alternatives.
|
|
23
|
-
|
|
24
|
-
## Quick Comparison
|
|
25
|
-
|
|
26
|
-
| Feature | Cronicorn | Trigger.dev | Inngest | Temporal | QStash | n8n | Windmill |
|
|
27
|
-
|---------|-----------|-------------|---------|----------|--------|-----|----------|
|
|
28
|
-
| **AI-Adaptive Scheduling** | ✅ Core Feature | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
|
|
29
|
-
| **HTTP Endpoint Execution** | ✅ | ✅ | ✅ | ⚠️ Manual | ✅ | ✅ | ✅ |
|
|
30
|
-
| **Cron/Interval Scheduling** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
31
|
-
| **Self-Hosted** | ✅ Free | ✅ Complex | ✅ Free | ✅ Complex | ❌ | ✅ Free | ✅ Free |
|
|
32
|
-
| **Entry Price** | Free (soon) | $10/mo | Free | $100/mo | Free | Free | Free |
|
|
33
|
-
| **Learning Curve** | Low | Medium | Medium | High | Low | Low | High |
|
|
34
|
-
| **Best For** | HTTP health checks, API polling, adaptive workflows | AI workflows, TypeScript apps | Event-driven serverless | Enterprise orchestration | Simple webhooks | Visual workflows, integrations | Internal tools |
|
|
35
|
-
|
|
36
|
-
### At a Glance
|
|
37
|
-
|
|
38
|
-
**Cronicorn** = Cron that learns and adapts automatically
|
|
39
|
-
**Trigger.dev** = Code-first workflow orchestration for TypeScript
|
|
40
|
-
**Inngest** = Event-driven serverless background jobs
|
|
41
|
-
**Temporal** = Enterprise workflow engine for distributed systems
|
|
42
|
-
**QStash** = Serverless HTTP message queue
|
|
43
|
-
**n8n** = Visual workflow automation with 400+ integrations
|
|
44
|
-
**Windmill** = Developer platform for internal tools
|
|
45
|
-
|
|
46
|
-
---
|
|
47
|
-
|
|
48
|
-
## 🎯 Why Choose Cronicorn?
|
|
49
|
-
|
|
50
|
-
### 1. **True AI-Powered Adaptation**
|
|
51
|
-
|
|
52
|
-
**Cronicorn is the only platform that automatically adjusts job timing based on real-world performance.**
|
|
53
|
-
|
|
54
|
-
While other platforms offer static scheduling or complex workflow orchestration, Cronicorn learns from your endpoints:
|
|
55
|
-
|
|
56
|
-
- **Backs off automatically** when detecting rate limits or failures
|
|
57
|
-
- **Speeds up** when detecting backlogs or increased activity
|
|
58
|
-
- **Maintains stability** by slowing execution during idle periods
|
|
59
|
-
- **Stays within your constraints** - AI respects your min/max limits
|
|
60
|
-
|
|
61
|
-
**Example**: Your health check runs every 5 minutes baseline. When errors spike, Cronicorn adapts to every 30 seconds. When everything's stable for hours, it backs off to every 15 minutes—all automatically.
|
|
62
|
-
|
|
63
|
-
**Competitors**: Static schedules that run regardless of conditions. You manually adjust based on metrics.
|
|
64
|
-
|
|
65
|
-
---
|
|
66
|
-
|
|
67
|
-
### 2. **Simplicity for HTTP Job Scheduling**
|
|
68
|
-
|
|
69
|
-
**Cronicorn is purpose-built for HTTP endpoints. Others require complex setup.**
|
|
70
|
-
|
|
71
|
-
- **Trigger.dev**: Requires writing TypeScript code, deploying functions, managing builds
|
|
72
|
-
- **Inngest**: Event-driven model adds complexity for simple polling
|
|
73
|
-
- **Temporal**: Heavy enterprise framework, steep learning curve
|
|
74
|
-
- **Windmill**: Powerful but requires learning workflow DSL and script management
|
|
75
|
-
|
|
76
|
-
**Cronicorn**: Define a URL, set baseline schedule, done. Optional AI optimization with zero code changes.
|
|
77
|
-
|
|
78
|
-
```json
|
|
79
|
-
{
|
|
80
|
-
"name": "Health Check",
|
|
81
|
-
"url": "https://api.example.com/health",
|
|
82
|
-
"method": "GET",
|
|
83
|
-
"baselineIntervalMs": 300000,
|
|
84
|
-
"minIntervalMs": 30000,
|
|
85
|
-
"maxIntervalMs": 900000
|
|
86
|
-
}
|
|
87
|
-
```
|
|
88
|
-
|
|
89
|
-
---
|
|
90
|
-
|
|
91
|
-
### 3. **Transparent, Explainable Scheduling**
|
|
92
|
-
|
|
93
|
-
**Every scheduling decision is explained in plain English.**
|
|
94
|
-
|
|
95
|
-
Cronicorn shows you exactly why each job ran when it did:
|
|
96
|
-
|
|
97
|
-
- "Baseline cron schedule (every 5 minutes)"
|
|
98
|
-
- "AI increased frequency—3 consecutive failures detected"
|
|
99
|
-
- "AI decreased interval—stable for 2 hours, no errors"
|
|
100
|
-
- "Clamped to minimum interval (rate limit protection)"
|
|
101
|
-
|
|
102
|
-
**Competitors**: Black-box scheduling. You see *when* jobs run, but not *why* the timing was chosen.
|
|
103
|
-
|
|
104
|
-
---
|
|
105
|
-
|
|
106
|
-
### 4. **Constraint Protection Built-In**
|
|
107
|
-
|
|
108
|
-
**Safety constraints prevent runaway costs and rate limit violations.**
|
|
109
|
-
|
|
110
|
-
Set min/max intervals, and Cronicorn guarantees:
|
|
111
|
-
- ✅ Jobs never run faster than your minimum (protects rate limits)
|
|
112
|
-
- ✅ Jobs never run slower than your maximum (ensures freshness)
|
|
113
|
-
- ✅ AI suggestions are always clamped to safe ranges
|
|
114
|
-
|
|
115
|
-
**Example**: API allows 100 requests/hour. Set min interval to 36 seconds—Cronicorn will never exceed your quota, even with AI enabled.
|
|
116
|
-
|
|
117
|
-
**Competitors**: QStash and Trigger.dev have rate limiting, but not adaptive constraint-aware scheduling.
|
|
118
|
-
|
|
119
|
-
---
|
|
120
|
-
|
|
121
|
-
### 5. **Works Without AI**
|
|
122
|
-
|
|
123
|
-
**Cronicorn is a production-ready scheduler even without AI.**
|
|
124
|
-
|
|
125
|
-
The baseline scheduler is:
|
|
126
|
-
- Reliable (database-backed with distributed locks)
|
|
127
|
-
- Flexible (cron expressions or simple intervals)
|
|
128
|
-
- Complete (pause/resume, run history, error tracking)
|
|
129
|
-
|
|
130
|
-
Enable AI when you want optimization. Disable it if you prefer predictable behavior.
|
|
131
|
-
|
|
132
|
-
**Competitors**: All-or-nothing. You get their workflow model or nothing.
|
|
133
|
-
|
|
134
|
-
---
|
|
135
|
-
|
|
136
|
-
## Platform-by-Platform Comparison
|
|
137
|
-
|
|
138
|
-
### 🆚 Cronicorn vs. Trigger.dev
|
|
139
|
-
|
|
140
|
-
**Trigger.dev** is excellent for complex, multi-step workflows and AI agent orchestration in TypeScript.
|
|
141
|
-
|
|
142
|
-
| What Trigger.dev Does Better | What Cronicorn Does Better |
|
|
143
|
-
|------------------------------|---------------------------|
|
|
144
|
-
| Multi-step workflow orchestration | Automatic schedule adaptation |
|
|
145
|
-
| Built-in AI SDK integrations | Zero-code HTTP job scheduling |
|
|
146
|
-
| TypeScript-native development | Transparent scheduling decisions |
|
|
147
|
-
| Real-time streaming to frontend | Constraint-based safety |
|
|
148
|
-
| Long-running background jobs | Simple setup for HTTP endpoints |
|
|
149
|
-
|
|
150
|
-
**Choose Trigger.dev if**: You need complex, code-based workflows with multiple steps, retries, and AI integration.
|
|
151
|
-
|
|
152
|
-
**Choose Cronicorn if**: You want HTTP endpoints to run on adaptive schedules with minimal setup and automatic optimization.
|
|
153
|
-
|
|
154
|
-
**Use both**: Cronicorn schedules your Trigger.dev workflow endpoints, adapting their timing based on performance.
|
|
155
|
-
|
|
156
|
-
---
|
|
157
|
-
|
|
158
|
-
### 🆚 Cronicorn vs. Inngest
|
|
159
|
-
|
|
160
|
-
**Inngest** excels at event-driven architectures and serverless background jobs.
|
|
161
|
-
|
|
162
|
-
| What Inngest Does Better | What Cronicorn Does Better |
|
|
163
|
-
|-------------------------|---------------------------|
|
|
164
|
-
| Event-driven workflows | Time-based adaptive scheduling |
|
|
165
|
-
| Durable step functions | Explainable scheduling decisions |
|
|
166
|
-
| Built-in retry/recovery | AI learns from job performance |
|
|
167
|
-
| Multi-language SDKs (TS/Python/Go) | Simpler setup for cron jobs |
|
|
168
|
-
| Webhook transformations | Transparent min/max constraints |
|
|
169
|
-
|
|
170
|
-
**Choose Inngest if**: You have event-driven workflows triggered by user actions, webhooks, or app events.
|
|
171
|
-
|
|
172
|
-
**Choose Cronicorn if**: You need scheduled HTTP jobs that adapt their timing based on success rates and patterns.
|
|
173
|
-
|
|
174
|
-
**Use both**: Inngest handles event-driven logic; Cronicorn schedules the periodic data syncs and health checks.
|
|
175
|
-
|
|
176
|
-
---
|
|
177
|
-
|
|
178
|
-
### 🆚 Cronicorn vs. Temporal
|
|
179
|
-
|
|
180
|
-
**Temporal** is the gold standard for distributed workflow orchestration in enterprise environments.
|
|
181
|
-
|
|
182
|
-
| What Temporal Does Better | What Cronicorn Does Better |
|
|
183
|
-
|--------------------------|---------------------------|
|
|
184
|
-
| Long-running sagas and distributed transactions | Simple HTTP job scheduling |
|
|
185
|
-
| Enterprise-grade reliability | AI-powered schedule adaptation |
|
|
186
|
-
| Multi-language SDKs | Easy setup and maintenance |
|
|
187
|
-
| Fine-grained workflow control | Transparent, explainable timing |
|
|
188
|
-
| Advanced replay and versioning | Lower operational complexity |
|
|
189
|
-
|
|
190
|
-
**Pricing**: Temporal Cloud starts at $100/month; Cronicorn plans to be free for basic usage.
|
|
191
|
-
|
|
192
|
-
**Choose Temporal if**: You need bulletproof workflow orchestration for mission-critical distributed systems.
|
|
193
|
-
|
|
194
|
-
**Choose Cronicorn if**: You want HTTP endpoints to run on smart schedules without enterprise-level complexity.
|
|
195
|
-
|
|
196
|
-
**Use both**: Temporal orchestrates complex business processes; Cronicorn handles the adaptive scheduled triggers.
|
|
197
|
-
|
|
198
|
-
---
|
|
199
|
-
|
|
200
|
-
### 🆚 Cronicorn vs. QStash (Upstash)
|
|
201
|
-
|
|
202
|
-
**QStash** is a great serverless message queue for simple HTTP job delivery.
|
|
203
|
-
|
|
204
|
-
| What QStash Does Better | What Cronicorn Does Better |
|
|
205
|
-
|------------------------|---------------------------|
|
|
206
|
-
| Simple serverless pricing | AI-adaptive scheduling |
|
|
207
|
-
| Fan-out to multiple endpoints | Schedule optimization based on performance |
|
|
208
|
-
| Integration with Upstash ecosystem | Explainable scheduling decisions |
|
|
209
|
-
| Lower operational overhead | Constraint-aware adaptation |
|
|
210
|
-
| HTTP-first message queue | Real-time monitoring dashboard |
|
|
211
|
-
|
|
212
|
-
**Pricing**: QStash free tier (1k messages/day); paid plans start at $1 per 100k messages. Cronicorn plans similar affordability.
|
|
213
|
-
|
|
214
|
-
**Choose QStash if**: You need a simple message queue with retries and don't need adaptive scheduling.
|
|
215
|
-
|
|
216
|
-
**Choose Cronicorn if**: You want your scheduled jobs to automatically optimize timing based on real-world conditions.
|
|
217
|
-
|
|
218
|
-
**Use both**: QStash handles message delivery; Cronicorn schedules when those messages should be sent.
|
|
219
|
-
|
|
220
|
-
---
|
|
221
|
-
|
|
222
|
-
### 🆚 Cronicorn vs. Windmill
|
|
223
|
-
|
|
224
|
-
**Windmill** is a powerful open-source platform for internal tools and workflow automation.
|
|
225
|
-
|
|
226
|
-
| What Windmill Does Better | What Cronicorn Does Better |
|
|
227
|
-
|--------------------------|---------------------------|
|
|
228
|
-
| Script-to-UI generation | Focused HTTP job scheduling |
|
|
229
|
-
| Multi-language support (Python, Go, Rust, etc.) | AI-adaptive timing |
|
|
230
|
-
| Internal app builder | Simpler learning curve |
|
|
231
|
-
| Git-based workflow versioning | Transparent scheduling explanations |
|
|
232
|
-
| Extensive integrations library | Purpose-built for HTTP endpoints |
|
|
233
|
-
|
|
234
|
-
**Choose Windmill if**: You need a full developer platform for building internal tools, scripts, and complex workflows.
|
|
235
|
-
|
|
236
|
-
**Choose Cronicorn if**: You specifically need HTTP endpoints to run on adaptive, intelligent schedules.
|
|
237
|
-
|
|
238
|
-
**Use both**: Windmill builds your internal automation scripts; Cronicorn schedules them with adaptive timing.
|
|
239
|
-
|
|
240
|
-
---
|
|
241
|
-
|
|
242
|
-
### 🆚 Cronicorn vs. n8n
|
|
243
|
-
|
|
244
|
-
**n8n** is a popular open-source workflow automation platform with a visual node-based editor and 400+ integrations.
|
|
245
|
-
|
|
246
|
-
| What n8n Does Better | What Cronicorn Does Better |
|
|
247
|
-
|---------------------|---------------------------|
|
|
248
|
-
| Visual workflow builder (drag-and-drop) | AI-adaptive scheduling |
|
|
249
|
-
| 400+ pre-built integrations | Purpose-built for HTTP endpoints |
|
|
250
|
-
| Multi-app workflow orchestration | Automatic schedule optimization |
|
|
251
|
-
| Low-code/no-code friendly | Explainable scheduling decisions |
|
|
252
|
-
| Custom JavaScript/Python in workflows | Constraint-aware adaptation |
|
|
253
|
-
|
|
254
|
-
**Pricing**: n8n free (self-hosted); Cloud starts at $20/mo (2,500 executions). Cronicorn plans similar affordability.
|
|
255
|
-
|
|
256
|
-
**Choose n8n if**: You need to connect multiple apps together in visual workflows, especially for non-developers.
|
|
257
|
-
|
|
258
|
-
**Choose Cronicorn if**: You need HTTP endpoints with intelligent, adaptive scheduling that learns from performance.
|
|
259
|
-
|
|
260
|
-
**Use both**: n8n orchestrates multi-step workflows; Cronicorn provides the adaptive scheduling trigger with webhooks. Many teams use Cronicorn to trigger n8n workflows at optimized times based on real conditions.
|
|
261
|
-
|
|
262
|
-
---
|
|
263
|
-
|
|
264
|
-
## What Makes Cronicorn Unique?
|
|
265
|
-
|
|
266
|
-
### The "Adaptive Cron" Gap
|
|
267
|
-
|
|
268
|
-
Every existing tool falls into one of two categories:
|
|
269
|
-
|
|
270
|
-
1. **Static cron schedulers** - Run jobs at fixed intervals, regardless of conditions
|
|
271
|
-
2. **Complex workflow engines** - Powerful orchestration, but require significant setup
|
|
272
|
-
|
|
273
|
-
**Cronicorn is the first to offer adaptive, intelligent scheduling for HTTP endpoints without the complexity.**
|
|
274
|
-
|
|
275
|
-
We fill the gap between "too simple" and "too complex":
|
|
276
|
-
|
|
277
|
-
1. **Simpler than workflow engines** - No code deployment, no learning DSLs, just configure a URL
|
|
278
|
-
2. **Smarter than static cron** - Learns and adapts automatically based on actual performance
|
|
279
|
-
3. **Safer than manual tuning** - Built-in constraints prevent runaway schedules and rate limit violations
|
|
280
|
-
4. **More transparent than black boxes** - Every decision is explained in plain English
|
|
281
|
-
|
|
282
|
-
### When Cronicorn Shines
|
|
283
|
-
|
|
284
|
-
**Perfect for these use cases:**
|
|
285
|
-
|
|
286
|
-
✅ **API Health Monitoring** - Automatically increase check frequency when errors occur, back off when stable
|
|
287
|
-
✅ **Data Synchronization** - Speed up during business hours when changes are frequent, slow down overnight
|
|
288
|
-
✅ **Web Scraping** - Intelligently back off when rate-limited, resume optimal frequency when quota resets
|
|
289
|
-
✅ **Webhook Retries** - Adaptive exponential backoff based on downstream service patterns
|
|
290
|
-
✅ **Scheduled Maintenance** - Run within maintenance windows while adapting to system load
|
|
291
|
-
✅ **External API Polling** - Optimize request frequency based on data freshness and change patterns
|
|
292
|
-
|
|
293
|
-
### When to Consider Alternatives
|
|
294
|
-
|
|
295
|
-
**Consider these platforms when you need:**
|
|
296
|
-
|
|
297
|
-
- **Trigger.dev**: Multi-step TypeScript workflows, AI agent orchestration, complex retry logic
|
|
298
|
-
- **Inngest**: Event-driven serverless architectures triggered by user actions or webhooks
|
|
299
|
-
- **Temporal**: Enterprise-grade distributed workflow orchestration with saga patterns
|
|
300
|
-
- **QStash**: Simple serverless message queue without adaptive scheduling needs
|
|
301
|
-
- **n8n**: Visual workflow automation connecting multiple apps with drag-and-drop interface
|
|
302
|
-
- **Windmill**: Full internal tool platform with script-to-UI generation
|
|
303
|
-
|
|
304
|
-
**Or combine them**: Many teams use Cronicorn for adaptive scheduling alongside these platforms for workflow orchestration.
|
|
305
|
-
|
|
306
|
-
---
|
|
307
|
-
|
|
308
|
-
## Pricing Comparison (Early 2025)
|
|
309
|
-
|
|
310
|
-
| Platform | Free Tier | Starter Plan | Enterprise |
|
|
311
|
-
|----------|-----------|--------------|------------|
|
|
312
|
-
| **Cronicorn** | Coming soon | Coming soon | Contact |
|
|
313
|
-
| **Trigger.dev** | 5 credits/mo | $10/mo (10 credits) | Custom |
|
|
314
|
-
| **Inngest** | 50k executions/mo | $75/mo (1M executions) | Custom |
|
|
315
|
-
| **Temporal Cloud** | Self-host only | $100/mo | Custom |
|
|
316
|
-
| **QStash** | 1k messages/day | Pay-as-you-go ($1/100k) | Custom |
|
|
317
|
-
| **n8n** | Self-host free | $20/mo (2,500 executions) | Custom |
|
|
318
|
-
| **Windmill** | Self-host free | $120/mo cloud | $170/mo self-hosted |
|
|
319
|
-
|
|
320
|
-
**Cronicorn's pricing philosophy**: Simple, affordable, transparent. Coming soon.
|
|
321
|
-
|
|
322
|
-
---
|
|
323
|
-
|
|
324
|
-
*Last updated: November 2025. Competitor information based on publicly available documentation and pricing as of this date.*
|
|
@@ -1,29 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: developers-overview
|
|
3
|
-
title: Developer Overview
|
|
4
|
-
description: Documentation for developers contributing to Cronicorn
|
|
5
|
-
tags:
|
|
6
|
-
- developer
|
|
7
|
-
sidebar_position: 0
|
|
8
|
-
mcp:
|
|
9
|
-
uri: file:///docs/developers/overview.md
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
# Developer Documentation
|
|
13
|
-
|
|
14
|
-
Documentation for developers contributing to Cronicorn's codebase or building AI agents that interact with Cronicorn.
|
|
15
|
-
|
|
16
|
-
## Getting Started
|
|
17
|
-
|
|
18
|
-
- **[Quick Start](./quick-start.md)** - Set up your development environment in 4 steps
|
|
19
|
-
- **[Authentication](./authentication.md)** - Configure admin user or GitHub OAuth
|
|
20
|
-
- **[Workspace Structure](./workspace-structure.md)** - Monorepo organization (apps and packages)
|
|
21
|
-
- **[Quality Checks](./quality-checks.md)** - Required checks before committing and merging
|
|
22
|
-
|
|
23
|
-
## Architecture & Design
|
|
24
|
-
|
|
25
|
-
- **[System Architecture](../technical/system-architecture.md)** - Core concepts and design patterns
|
|
26
|
-
|
|
27
|
-
## Contributing
|
|
28
|
-
|
|
29
|
-
For contributors working on Cronicorn's codebase, additional technical guidelines are available in the repository's `.github/instructions/` directory.
|
|
@@ -1,121 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: developer-authentication
|
|
3
|
-
title: Authentication Configuration
|
|
4
|
-
description: Configure GitHub OAuth, API keys, and programmatic access
|
|
5
|
-
tags:
|
|
6
|
-
- developer
|
|
7
|
-
- configuration
|
|
8
|
-
sidebar_position: 2
|
|
9
|
-
mcp:
|
|
10
|
-
uri: file:///docs/developers/authentication.md
|
|
11
|
-
mimeType: text/markdown
|
|
12
|
-
priority: 0.8
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
# Authentication Configuration
|
|
16
|
-
|
|
17
|
-
> **Getting started?** See [Quick Start](./quick-start.md) - no configuration required for local development.
|
|
18
|
-
|
|
19
|
-
This guide covers advanced authentication setup: GitHub OAuth for production, API keys, and programmatic access.
|
|
20
|
-
|
|
21
|
-
## Authentication Methods
|
|
22
|
-
|
|
23
|
-
| Method | Use Case | Setup Required |
|
|
24
|
-
|--------|----------|----------------|
|
|
25
|
-
| Admin User | Local dev, self-hosting | None (works by default) |
|
|
26
|
-
| GitHub OAuth | Production with multiple users | GitHub OAuth app |
|
|
27
|
-
| API Keys | Service-to-service | Generate in web UI |
|
|
28
|
-
| Bearer Tokens | CLI/AI agents | Device authorization flow |
|
|
29
|
-
|
|
30
|
-
## GitHub OAuth Setup
|
|
31
|
-
|
|
32
|
-
Best for production deployments with multiple users.
|
|
33
|
-
|
|
34
|
-
**1. [Create GitHub OAuth app](https://github.com/settings/developers)**
|
|
35
|
-
|
|
36
|
-
**2. Set callback URL:**
|
|
37
|
-
```
|
|
38
|
-
${BETTER_AUTH_URL}/api/auth/callback/github
|
|
39
|
-
```
|
|
40
|
-
Example: `https://api.yourdomain.com/api/auth/callback/github`
|
|
41
|
-
|
|
42
|
-
**3. Add to `.env`:**
|
|
43
|
-
```bash
|
|
44
|
-
GITHUB_CLIENT_ID=your_client_id
|
|
45
|
-
GITHUB_CLIENT_SECRET=your_client_secret
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
**4. Restart the app** - "Sign in with GitHub" button will appear
|
|
49
|
-
|
|
50
|
-
## Programmatic Access
|
|
51
|
-
|
|
52
|
-
### API Keys
|
|
53
|
-
|
|
54
|
-
Generate in web UI at `/settings/api-keys`:
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
curl -H "X-API-Key: your-api-key" \
|
|
58
|
-
http://localhost:3333/api/jobs
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
### Bearer Tokens (CLI/AI Agents)
|
|
62
|
-
|
|
63
|
-
Use the OAuth device authorization flow:
|
|
64
|
-
|
|
65
|
-
```bash
|
|
66
|
-
# 1. Initiate device flow
|
|
67
|
-
curl -X POST http://localhost:3333/api/auth/device/code
|
|
68
|
-
|
|
69
|
-
# 2. User authorizes in browser at the provided URL
|
|
70
|
-
|
|
71
|
-
# 3. Poll for token
|
|
72
|
-
curl -X POST http://localhost:3333/api/auth/device/token \
|
|
73
|
-
-d "device_code=DEVICE_CODE"
|
|
74
|
-
|
|
75
|
-
# 4. Use in API requests
|
|
76
|
-
curl -H "Authorization: Bearer TOKEN" \
|
|
77
|
-
http://localhost:3333/api/jobs
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
## Production Configuration
|
|
81
|
-
|
|
82
|
-
```bash
|
|
83
|
-
# Required: Secure secret (generate with: openssl rand -base64 32)
|
|
84
|
-
BETTER_AUTH_SECRET=your-secure-random-secret-min-32-chars
|
|
85
|
-
|
|
86
|
-
# Required: Production URLs
|
|
87
|
-
BETTER_AUTH_URL=https://api.yourdomain.com
|
|
88
|
-
WEB_URL=https://yourdomain.com
|
|
89
|
-
|
|
90
|
-
# Option A: Admin user for emergency access
|
|
91
|
-
ADMIN_USER_EMAIL=admin@yourdomain.com
|
|
92
|
-
ADMIN_USER_PASSWORD=${SECRET_FROM_VAULT}
|
|
93
|
-
|
|
94
|
-
# Option B: GitHub OAuth for regular users
|
|
95
|
-
GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
|
|
96
|
-
GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
> ⚠️ **Security**: Use a secrets manager in production, not plain `.env` files.
|
|
100
|
-
|
|
101
|
-
## Validation Rules
|
|
102
|
-
|
|
103
|
-
At least one authentication method must be configured:
|
|
104
|
-
|
|
105
|
-
| Configuration | Status |
|
|
106
|
-
|---------------|--------|
|
|
107
|
-
| Admin user only | ✅ Works |
|
|
108
|
-
| GitHub OAuth only | ✅ Works |
|
|
109
|
-
| Both enabled | ✅ Works |
|
|
110
|
-
| Neither enabled | ❌ App won't start |
|
|
111
|
-
|
|
112
|
-
## Troubleshooting
|
|
113
|
-
|
|
114
|
-
**Login returns 404?**
|
|
115
|
-
→ Restart API server after changing `.env`
|
|
116
|
-
|
|
117
|
-
**Admin user not created?**
|
|
118
|
-
→ Run `pnpm db:seed` or check logs for "Admin user created"
|
|
119
|
-
|
|
120
|
-
**GitHub OAuth not working?**
|
|
121
|
-
→ Verify callback URL matches `${BETTER_AUTH_URL}/api/auth/callback/github`
|
|
@@ -1,103 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: environment-configuration
|
|
3
|
-
title: Environment Configuration
|
|
4
|
-
description: Complete reference for all Cronicorn environment variables
|
|
5
|
-
tags:
|
|
6
|
-
- developer
|
|
7
|
-
- configuration
|
|
8
|
-
- reference
|
|
9
|
-
sidebar_position: 3
|
|
10
|
-
---
|
|
11
|
-
|
|
12
|
-
# Environment Configuration
|
|
13
|
-
|
|
14
|
-
> **Getting started?** See [Quick Start](./quick-start.md) - no configuration required for local development.
|
|
15
|
-
|
|
16
|
-
This is the complete reference for all environment variables. Local development works out of the box with sensible defaults.
|
|
17
|
-
|
|
18
|
-
## Default Values
|
|
19
|
-
|
|
20
|
-
All defaults are maintained in `@cronicorn/config-defaults` for consistency across apps.
|
|
21
|
-
|
|
22
|
-
### Development Defaults (No .env Required)
|
|
23
|
-
|
|
24
|
-
| Category | Variable | Default |
|
|
25
|
-
|----------|----------|---------|
|
|
26
|
-
| **Auth** | `ADMIN_USER_EMAIL` | `admin@example.com` |
|
|
27
|
-
| | `ADMIN_USER_PASSWORD` | `devpassword` |
|
|
28
|
-
| | `BETTER_AUTH_SECRET` | `dev-secret-DO-NOT-USE...` |
|
|
29
|
-
| **Database** | `DATABASE_URL` | `postgresql://user:password@localhost:6666/db` |
|
|
30
|
-
| **URLs** | `BETTER_AUTH_URL` | `http://localhost:3333` |
|
|
31
|
-
| | `WEB_URL` | `http://localhost:5173` |
|
|
32
|
-
| | `API_URL` | `http://localhost:3333` |
|
|
33
|
-
| **Ports** | `API_PORT` | `3333` |
|
|
34
|
-
| | `WEB_PORT` | `5173` |
|
|
35
|
-
| | `DB_PORT` | `6666` |
|
|
36
|
-
| **Stripe** | `STRIPE_SECRET_KEY` | `sk_test_dummy_key...` |
|
|
37
|
-
| | `STRIPE_WEBHOOK_SECRET` | `whsec_test_dummy...` |
|
|
38
|
-
|
|
39
|
-
⚠️ **Security**: These defaults are for local development only. Production must override them.
|
|
40
|
-
|
|
41
|
-
## Customizing for Local Development
|
|
42
|
-
|
|
43
|
-
To override defaults locally, create a `.env` file:
|
|
44
|
-
|
|
45
|
-
```bash
|
|
46
|
-
cp .env.example .env
|
|
47
|
-
# Edit only the variables you need to change
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
## Production Deployment
|
|
51
|
-
|
|
52
|
-
Production deployments MUST override these variables:
|
|
53
|
-
|
|
54
|
-
```bash
|
|
55
|
-
# 1. Secure auth secret (generate with: openssl rand -base64 32)
|
|
56
|
-
BETTER_AUTH_SECRET=your-secure-random-secret-min-32-chars
|
|
57
|
-
|
|
58
|
-
# 2. Production URLs
|
|
59
|
-
WEB_URL=https://yourdomain.com
|
|
60
|
-
API_URL=https://api.yourdomain.com
|
|
61
|
-
BETTER_AUTH_URL=https://api.yourdomain.com
|
|
62
|
-
|
|
63
|
-
# 3. Authentication (at least one required)
|
|
64
|
-
ADMIN_USER_EMAIL=admin@yourcompany.com
|
|
65
|
-
ADMIN_USER_PASSWORD=strong-unique-password
|
|
66
|
-
# OR
|
|
67
|
-
GITHUB_CLIENT_ID=your_github_client_id
|
|
68
|
-
GITHUB_CLIENT_SECRET=your_github_client_secret
|
|
69
|
-
|
|
70
|
-
# 4. Stripe (if using payments)
|
|
71
|
-
STRIPE_SECRET_KEY=sk_live_your_production_key
|
|
72
|
-
STRIPE_WEBHOOK_SECRET=whsec_your_production_webhook_secret
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
The app validates on startup and exits if dev defaults are used in production.
|
|
76
|
-
|
|
77
|
-
## Architecture
|
|
78
|
-
|
|
79
|
-
Defaults are centralized in `@cronicorn/config-defaults` and imported by each app:
|
|
80
|
-
|
|
81
|
-
```
|
|
82
|
-
packages/config-defaults/src/index.ts # Single source of truth
|
|
83
|
-
apps/api/src/lib/config.ts # API imports defaults
|
|
84
|
-
apps/scheduler/src/index.ts # Scheduler imports defaults
|
|
85
|
-
apps/web/src/config.ts # Web imports defaults
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
## Troubleshooting
|
|
89
|
-
|
|
90
|
-
**"Cannot find module @cronicorn/config-defaults"**
|
|
91
|
-
→ Run `pnpm build:packages`
|
|
92
|
-
|
|
93
|
-
**"Environment variable validation failed"**
|
|
94
|
-
→ Check the error message for which variable is invalid
|
|
95
|
-
|
|
96
|
-
**"Auth not working in production"**
|
|
97
|
-
→ Ensure you've overridden `BETTER_AUTH_SECRET` and `ADMIN_USER_PASSWORD`
|
|
98
|
-
|
|
99
|
-
## Related
|
|
100
|
-
|
|
101
|
-
- **[Quick Start](./quick-start.md)** - Get running with zero config
|
|
102
|
-
- **[Authentication](./authentication.md)** - GitHub OAuth, API keys, programmatic access
|
|
103
|
-
- **[Workspace Structure](./workspace-structure.md)** - Project organization
|
|
@@ -1,68 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
id: developer-quality-checks
|
|
3
|
-
title: Quality Checks
|
|
4
|
-
description: Required quality checks before committing and merging code
|
|
5
|
-
tags:
|
|
6
|
-
- developer
|
|
7
|
-
- quality
|
|
8
|
-
- testing
|
|
9
|
-
sidebar_position: 4
|
|
10
|
-
mcp:
|
|
11
|
-
uri: file:///docs/developers/quality-checks.md
|
|
12
|
-
mimeType: text/markdown
|
|
13
|
-
priority: 0.75
|
|
14
|
-
---
|
|
15
|
-
|
|
16
|
-
# Quality Checks
|
|
17
|
-
|
|
18
|
-
## Before Commit
|
|
19
|
-
|
|
20
|
-
```bash
|
|
21
|
-
pnpm test # Unit & integration tests (excludes e2e)
|
|
22
|
-
pnpm lint # Check for errors
|
|
23
|
-
pnpm build:packages # Ensure types compile
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## Before Merge
|
|
27
|
-
|
|
28
|
-
```bash
|
|
29
|
-
pnpm test # Full test suite (excludes e2e)
|
|
30
|
-
pnpm lint:fix # Fix and verify (zero warnings)
|
|
31
|
-
pnpm build # Full build
|
|
32
|
-
pnpm test:e2e # E2E tests (separate command)
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
## What to Test
|
|
36
|
-
|
|
37
|
-
| Change | Test Type |
|
|
38
|
-
|--------|-----------|
|
|
39
|
-
| Domain logic | Unit tests (mocked ports) |
|
|
40
|
-
| Repositories | Integration tests (transaction-per-test) |
|
|
41
|
-
| API routes | API + integration tests |
|
|
42
|
-
| Bug fixes | Regression test |
|
|
43
|
-
|
|
44
|
-
**Coverage**: 80%+ for managers/services
|
|
45
|
-
|
|
46
|
-
## Common Fixes
|
|
47
|
-
|
|
48
|
-
**Tests fail**: `pnpm db` (ensure database running)
|
|
49
|
-
**Module errors**: `pnpm build:packages`
|
|
50
|
-
**Lint errors**: `pnpm lint:fix` (auto-fix most issues)
|
|
51
|
-
|
|
52
|
-
## Checklist
|
|
53
|
-
|
|
54
|
-
**Before Commit**
|
|
55
|
-
- [ ] Tests pass for changed packages
|
|
56
|
-
- [ ] No lint errors
|
|
57
|
-
- [ ] Packages build
|
|
58
|
-
|
|
59
|
-
**Before Merge**
|
|
60
|
-
- [ ] Full test suite passes
|
|
61
|
-
- [ ] Full build succeeds
|
|
62
|
-
- [ ] Zero lint warnings
|
|
63
|
-
- [ ] E2E tests pass (if applicable)
|
|
64
|
-
- [ ] ADR created (if architectural decision)
|
|
65
|
-
|
|
66
|
-
## Related
|
|
67
|
-
|
|
68
|
-
- **[Quick Start](./quick-start.md)** - Dev environment setup
|