Skip to content

Commit 50ca2b7

Browse files
danstarnsdanstarns
committed
updates to align with agents
1 parent e54a305 commit 50ca2b7

File tree

4 files changed

+357
-1
lines changed

4 files changed

+357
-1
lines changed

‎apps/connect-app.mdx‎

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: "Connect Your App"
3+
description: "Integrate your App with external services and databases"
4+
"og:title": "Connect Your App - Apps"
5+
---
6+
7+
Apps become powerful when they can connect to external systems. Hypermode
8+
supports connecting your app to APIs, databases, and model providers through
9+
secure, manageable integrations.
10+
11+
## Connection Examples
12+
13+
### OpenAI API connection
14+
15+
Connect to OpenAI for language models:
16+
17+
```json modus.json
18+
{
19+
"models": {
20+
"text-generator": {
21+
"sourceModel": "gpt-4o-mini",
22+
"connection": "openai",
23+
"path": "v1/chat/completions"
24+
}
25+
},
26+
"connections": {
27+
"openai": {
28+
"type": "http",
29+
"baseUrl": "https://api.openai.com/",
30+
"headers": {
31+
"Authorization": "Bearer {{API_KEY}}"
32+
}
33+
}
34+
}
35+
}
36+
```
37+
38+
### PostgreSQL database
39+
40+
Connect to a PostgreSQL database:
41+
42+
```json modus.json
43+
{
44+
"connections": {
45+
"postgres": {
46+
"type": "postgresql",
47+
"connStr": "{{DATABASE_URL}}"
48+
}
49+
}
50+
}
51+
```
52+
53+
### Dgraph database
54+
55+
Connect to a Dgraph database for graph operations:
56+
57+
```json modus.json
58+
{
59+
"connections": {
60+
"dgraph": {
61+
"type": "dgraph",
62+
"grpcTarget": "{{DGRAPH_ENDPOINT}}"
63+
}
64+
}
65+
}
66+
```
67+
68+
## Environment variables
69+
70+
### Naming convention
71+
72+
Hypermode uses a consistent naming pattern for environment variables:
73+
`MODUS_<CONNECTION_NAME>_<PLACEHOLDER>`
74+
75+
For a connection named `openai` with placeholder `{{API_KEY}}`:
76+
77+
- Environment variable: `MODUS_OPENAI_API_KEY`
78+
79+
### Local development
80+
81+
Set environment variables in `.env.dev.local`:
82+
83+
```text .env.dev.local
84+
MODUS_OPENAI_API_KEY="your_openai_api_key"
85+
MODUS_POSTGRES_DATABASE_URL="postgresql://localhost:5432/mydb"
86+
MODUS_DGRAPH_DGRAPH_ENDPOINT="localhost:9080"
87+
```
88+
89+
### Production environment
90+
91+
Configure production environment variables in the Hypermode console:
92+
93+
<img
94+
src="/images/apps/console-envs.png"
95+
alt="Environment variables configuration panel"
96+
/>
97+
98+
1. Navigate to your app in the console
99+
2. Click on the **Environment Variables** tab
100+
3. Add your environment variables with the proper naming convention
101+
4. Save the configuration
102+
103+
## Testing connections
104+
105+
### Local testing
106+
107+
Test connections during development:
108+
109+
```bash
110+
# Start development server
111+
modus dev
112+
113+
# Test connections in the API Explorer
114+
# Navigate to http://localhost:8686/explorer
115+
```
116+
117+
### Production testing
118+
119+
Verify connections in production:
120+
121+
```bash
122+
# Test your deployed app's connections
123+
curl -X POST https://your-app-endpoint.hypermode.app/graphql \
124+
-H "Authorization: Bearer YOUR_API_KEY" \
125+
-H "Content-Type: application/json" \
126+
-d '{"query": "{ testConnection }"}'
127+
```
128+
129+
## Best practices
130+
131+
- **Never commit secrets**: Use environment variables for all sensitive data
132+
- **Use least privilege**: Grant minimal necessary permissions to API tokens
133+
- **Test locally first**: Use `modus dev` to debug connection issues before
134+
deploying
135+
- **Monitor usage**: Track API calls and database connections in production
136+
137+
Your app can now securely connect to external services and databases.

‎apps/create-app.mdx‎

Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
---
2+
title: "Create Your App"
3+
description: "Get started by creating your first App in Hypermode"
4+
"og:title": "Create Your App - Apps"
5+
---
6+
7+
Creating your first App in Hypermode is straightforward. This guide walks you
8+
through the entire process from workspace creation to having a fully configured
9+
app ready for development.
10+
11+
## Prerequisites
12+
13+
Before creating your app, ensure you have:
14+
15+
- A GitHub account
16+
- Access to a repository (existing or new)
17+
- Basic understanding of your app's requirements
18+
19+
## Getting started
20+
21+
To create your app, follow these steps in the Hypermode console. If you haven't
22+
created a workspace yet, you'll need to do that first. Workspaces are where you
23+
and your team manage all your apps and configurations.
24+
25+
<Steps>
26+
27+
<Step title="Create your workspace">
28+
29+
Start by going to [hypermode.com](https://hypermode.com) and creating your
30+
workspace. Workspaces are where you and your team manage all your apps.
31+
32+
<img
33+
src="/images/apps/workspace-creation.png"
34+
alt="Create workspace interface showing workspace name input field"
35+
/>
36+
37+
Enter a descriptive name for your workspace and click **Create workspace**.
38+
Choose a name that reflects your organization or project scope, as this becomes
39+
the container for all your apps.
40+
41+
</Step>
42+
43+
<Step title="Navigate to Apps">
44+
45+
Once your workspace is created, you'll see the main dashboard. Click on **Apps**
46+
to start creating your first app.
47+
48+
<img
49+
src="/images/apps/workspace-landing.png"
50+
alt="Hypermode dashboard showing Apps option"
51+
/>
52+
53+
From the Apps section, you have options to create different types of apps or
54+
import existing ones.
55+
56+
</Step>
57+
58+
<Step title="Configure Your App">
59+
60+
Click **Import your Modus app** to create a new app. This option works whether
61+
you're importing an existing Modus project or starting fresh.
62+
63+
<img
64+
src="/images/apps/app-create.png"
65+
alt="Import Modus app configuration form with app name, GitHub repository, and location fields"
66+
/>
67+
68+
### Define your app name
69+
70+
Enter a descriptive name for your app. This can be used in your app's endpoint
71+
URL and throughout the Hypermode console.
72+
73+
### Connect to your GitHub repository
74+
75+
You have two options:
76+
77+
#### Option 1: use an existing repository
78+
79+
- Select your repository from the dropdown
80+
- Ensure your repository has the proper Modus structure or is ready for app
81+
development
82+
83+
#### Option 2: create a new repository
84+
85+
If you don't have a repository yet, you can create one:
86+
87+
<img
88+
height="200"
89+
src="/images/apps/github-create.png"
90+
alt="GitHub repository creation interface with repository name field"
91+
style={{
92+
width: "80%",
93+
maxWidth: "400px",
94+
margin: "0 auto",
95+
display: "block",
96+
}}
97+
/>
98+
99+
1. Choose the repository owner (your organization or personal account)
100+
2. Enter a memorable repository name
101+
3. Add an optional description
102+
4. Create the repository
103+
5. Return to the app configuration and select your newly created repository
104+
105+
### Deployment location
106+
107+
Choose your preferred deployment region. This affects:
108+
109+
- **Latency**: Choose a region close to your users
110+
- **Compliance**: Select based on data residency requirements
111+
- **Performance**: Consider where your external services are hosted
112+
113+
</Step>
114+
115+
<Step title="Complete App Creation">
116+
117+
After filling in all the configuration details, click **Create App**. Hypermode
118+
then automatically:
119+
120+
1. Sets up your app infrastructure
121+
2. Configures the GitHub integration
122+
3. Generates your app's endpoint and API key
123+
4. Prepares your development environment
124+
125+
</Step>
126+
127+
<Step title="Review your App configuration">
128+
129+
Once created, you'll see your app's configuration panel:
130+
131+
<img
132+
src="/images/apps/console-app.png"
133+
alt="App details panel showing endpoint, GitHub repository, and API key information"
134+
/>
135+
136+
Your new app includes:
137+
138+
### Endpoint
139+
140+
Your production GraphQL endpoint where your app is accessible:
141+
142+
```text
143+
https://your-app-name-workspace-id.hypermode.app/graphql
144+
```
145+
146+
### GitHub repository
147+
148+
The connected repository for automatic deployments. Any push to the main branch
149+
triggers a deployment.
150+
151+
### API key
152+
153+
Your authentication key for accessing the app's API. Keep this secure and use it
154+
in your app headers:
155+
156+
```bash
157+
Authorization: Bearer YOUR_API_KEY
158+
```
159+
160+
</Step>
161+
162+
</Steps>
163+
164+
## Development Approaches
165+
166+
With your app created, you can choose between two development approaches:
167+
168+
### Code first development
169+
170+
- Use the Modus CLI locally
171+
- Full control over app structure
172+
- Traditional Git workflows
173+
- See the [Develop guide](/apps/develop) for setup instructions
174+
175+
### Conversational development
176+
177+
- Use Threads for AI-assisted development
178+
- Natural language app building
179+
- Rapid prototyping and iteration
180+
- See the Threads documentation for details
181+
182+
## Next steps
183+
184+
Now that your app is created:
185+
186+
1. **Set up local development** with `modus dev` (see
187+
[Develop guide](/apps/develop))
188+
2. **Configure connections** to external services (see
189+
[Connect Your App guide](/apps/connect-your-app))
190+
3. **Deploy your first version** by pushing to your repository (see
191+
[Deploy guide](/apps/deploy))
192+
193+
Your app is now ready for development. The GitHub integration is configured,
194+
your endpoint is live, and you have everything needed to start building your
195+
AI-powered app.
196+
197+
## Troubleshooting
198+
199+
**Repository not appearing in dropdown?**
200+
201+
- Ensure you have proper permissions to the repository
202+
- Check that the Hypermode GitHub App is installed on your organization/account
203+
204+
**App creation failed?**
205+
206+
- Verify your repository is accessible
207+
- Ensure the app name doesn't conflict with existing apps
208+
- Check that all required fields are filled correctly
209+
210+
**Need to change configuration?**
211+
212+
- Most settings can be updated later in the app's configuration panel
213+
- Repository connections can be modified in the app settings

‎apps/develop.mdx‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: "Develop"
3+
sidebarTitle: "Develop with Your App"
34
description: "Build and iterate on your Apps locally or in Threads"
45
"og:title": "Develop - Apps"
56
---

‎docs.json‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,12 @@
7070
},
7171
{
7272
"group": "Apps",
73-
"pages": ["apps/overview", "apps/develop", "apps/deploy"]
73+
"pages": [
74+
"apps/overview",
75+
"apps/create-app",
76+
"apps/connect-app",
77+
"apps/develop"
78+
]
7479
},
7580
{
7681
"group": "Graphs",

0 commit comments

Comments
 (0)