Skip to content

Commit 7769f1a

Browse files
johnymontanaryanfoxtylerdanstarns
authored
Hypermode Apps (#135)
* update Modus and Apps overview * * * * * * * * * * * * * * * trunk format * updates to align with agents * more updates to sync with agents * fix broken links * updated to latest go version in deploy doc * update seo title for apps --------- Co-authored-by: Ryan Fox-Tyler <[email protected]> Co-authored-by: Daniel Starns <[email protected]>
1 parent 8468501 commit 7769f1a

File tree

15 files changed

+801
-3
lines changed

15 files changed

+801
-3
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: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
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+
/>
92+
93+
1. Choose the repository owner (your organization or personal account)
94+
2. Enter a memorable repository name
95+
3. Add an optional description
96+
4. Create the repository
97+
5. Return to the app configuration and select your newly created repository
98+
99+
### Deployment location
100+
101+
Choose your preferred deployment region. This affects:
102+
103+
- **Latency**: Choose a region close to your users
104+
- **Compliance**: Select based on data residency requirements
105+
- **Performance**: Consider where your external services are hosted
106+
107+
</Step>
108+
109+
<Step title="Complete App Creation">
110+
111+
After filling in all the configuration details, click **Create App**. Hypermode
112+
then automatically:
113+
114+
1. Sets up your app infrastructure
115+
2. Configures the GitHub integration
116+
3. Generates your app's endpoint and API key
117+
4. Prepares your development environment
118+
119+
</Step>
120+
121+
<Step title="Review your App configuration">
122+
123+
Once created, you'll see your app's configuration panel:
124+
125+
<img
126+
src="/images/apps/console-app.png"
127+
alt="App details panel showing endpoint, GitHub repository, and API key information"
128+
/>
129+
130+
Your new app includes:
131+
132+
### Endpoint
133+
134+
Your production GraphQL endpoint where your app is accessible:
135+
136+
```text
137+
https://your-app-name-workspace-id.hypermode.app/graphql
138+
```
139+
140+
### GitHub repository
141+
142+
The connected repository for automatic deployments. Any push to the main branch
143+
triggers a deployment.
144+
145+
### API key
146+
147+
Your authentication key for accessing the app's API. Keep this secure and use it
148+
in your app headers:
149+
150+
```bash
151+
Authorization: Bearer YOUR_API_KEY
152+
```
153+
154+
</Step>
155+
156+
</Steps>
157+
158+
## Development Approaches
159+
160+
With your app created, you can choose between two development approaches:
161+
162+
### Code first development
163+
164+
- Use the Modus CLI locally
165+
- Full control over app structure
166+
- Traditional Git workflows
167+
- See the [Develop guide](/apps/develop-app) for setup instructions
168+
169+
### Conversational development
170+
171+
- Use Threads for AI-assisted development
172+
- Natural language app building
173+
- Rapid prototyping and iteration
174+
- See the Threads documentation for details
175+
176+
## Next steps
177+
178+
Now that your app is created:
179+
180+
1. **Set up local development** with `modus dev` (see
181+
[Develop guide](/apps/develop-app))
182+
2. **Configure connections** to external services (see
183+
[Connect Your App guide](/apps/connect-app))
184+
3. **Deploy your first version** by pushing to your repository (see
185+
[Deploy guide](/apps/deploy-app))
186+
187+
Your app is now ready for development. The GitHub integration is configured,
188+
your endpoint is live, and you have everything needed to start building your
189+
AI-powered app.
190+
191+
## Troubleshooting
192+
193+
**Repository not appearing in dropdown?**
194+
195+
- Ensure you have proper permissions to the repository
196+
- Check that the Hypermode GitHub App is installed on your organization/account
197+
198+
**App creation failed?**
199+
200+
- Verify your repository is accessible
201+
- Ensure the app name doesn't conflict with existing apps
202+
- Check that all required fields are filled correctly
203+
204+
**Need to change configuration?**
205+
206+
- Most settings can be updated later in the app's configuration panel
207+
- Repository connections can be modified in the app settings

0 commit comments

Comments
 (0)