Skip to content

Hypermode Apps #135

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.

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

Open
wants to merge 18 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
137 changes: 137 additions & 0 deletions apps/connect-app.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,137 @@
---
title: "Connect Your App"
description: "Integrate your App with external services and databases"
"og:title": "Connect Your App - Apps"
---

Apps become powerful when they can connect to external systems. Hypermode
supports connecting your app to APIs, databases, and model providers through
secure, manageable integrations.

## Connection Examples

### OpenAI API connection

Connect to OpenAI for language models:

```json modus.json
{
"models": {
"text-generator": {
"sourceModel": "gpt-4o-mini",
"connection": "openai",
"path": "v1/chat/completions"
}
},
"connections": {
"openai": {
"type": "http",
"baseUrl": "https://api.openai.com/",
"headers": {
"Authorization": "Bearer {{API_KEY}}"
}
}
}
}
```

### PostgreSQL database

Connect to a PostgreSQL database:

```json modus.json
{
"connections": {
"postgres": {
"type": "postgresql",
"connStr": "{{DATABASE_URL}}"
}
}
}
```

### Dgraph database

Connect to a Dgraph database for graph operations:

```json modus.json
{
"connections": {
"dgraph": {
"type": "dgraph",
"grpcTarget": "{{DGRAPH_ENDPOINT}}"
}
}
}
```

## Environment variables

### Naming convention

Hypermode uses a consistent naming pattern for environment variables:
`MODUS_<CONNECTION_NAME>_<PLACEHOLDER>`

For a connection named `openai` with placeholder `{{API_KEY}}`:

- Environment variable: `MODUS_OPENAI_API_KEY`

### Local development

Set environment variables in `.env.dev.local`:

```text .env.dev.local
MODUS_OPENAI_API_KEY="your_openai_api_key"
MODUS_POSTGRES_DATABASE_URL="postgresql://localhost:5432/mydb"
MODUS_DGRAPH_DGRAPH_ENDPOINT="localhost:9080"
```

### Production environment

Configure production environment variables in the Hypermode console:

<img
src="/images/apps/console-envs.png"
alt="Environment variables configuration panel"
/>

1. Navigate to your app in the console
2. Click on the **Environment Variables** tab
3. Add your environment variables with the proper naming convention
4. Save the configuration

## Testing connections

### Local testing

Test connections during development:

```bash
# Start development server
modus dev

# Test connections in the API Explorer
# Navigate to http://localhost:8686/explorer
```

### Production testing

Verify connections in production:

```bash
# Test your deployed app's connections
curl -X POST https://your-app-endpoint.hypermode.app/graphql \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "{ testConnection }"}'
```

## Best practices

- **Never commit secrets**: Use environment variables for all sensitive data
- **Use least privilege**: Grant minimal necessary permissions to API tokens
- **Test locally first**: Use `modus dev` to debug connection issues before
deploying
- **Monitor usage**: Track API calls and database connections in production

Your app can now securely connect to external services and databases.
207 changes: 207 additions & 0 deletions apps/create-app.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,207 @@
---
title: "Create Your App"
description: "Get started by creating your first App in Hypermode"
"og:title": "Create Your App - Apps"
---

Creating your first App in Hypermode is straightforward. This guide walks you
through the entire process from workspace creation to having a fully configured
app ready for development.

## Prerequisites

Before creating your app, ensure you have:

- A GitHub account
- Access to a repository (existing or new)
- Basic understanding of your app's requirements

## Getting started

To create your app, follow these steps in the Hypermode console. If you haven't
created a workspace yet, you'll need to do that first. Workspaces are where you
and your team manage all your apps and configurations.

<Steps>

<Step title="Create your workspace">

Start by going to [hypermode.com](https://hypermode.com) and creating your
workspace. Workspaces are where you and your team manage all your apps.

<img
src="/images/apps/workspace-creation.png"
alt="Create workspace interface showing workspace name input field"
/>

Enter a descriptive name for your workspace and click **Create workspace**.
Choose a name that reflects your organization or project scope, as this becomes
the container for all your apps.

</Step>

<Step title="Navigate to Apps">

Once your workspace is created, you'll see the main dashboard. Click on **Apps**
to start creating your first app.

<img
src="/images/apps/workspace-landing.png"
alt="Hypermode dashboard showing Apps option"
/>

From the Apps section, you have options to create different types of apps or
import existing ones.

</Step>

<Step title="Configure Your App">

Click **Import your Modus app** to create a new app. This option works whether
you're importing an existing Modus project or starting fresh.

<img
src="/images/apps/app-create.png"
alt="Import Modus app configuration form with app name, GitHub repository, and location fields"
/>

### Define your app name

Enter a descriptive name for your app. This can be used in your app's endpoint
URL and throughout the Hypermode console.

### Connect to your GitHub repository

You have two options:

#### Option 1: use an existing repository

- Select your repository from the dropdown
- Ensure your repository has the proper Modus structure or is ready for app
development

#### Option 2: create a new repository

If you don't have a repository yet, you can create one:

<img
height="200"
src="/images/apps/github-create.png"
alt="GitHub repository creation interface with repository name field"
/>

1. Choose the repository owner (your organization or personal account)
2. Enter a memorable repository name
3. Add an optional description
4. Create the repository
5. Return to the app configuration and select your newly created repository

### Deployment location

Choose your preferred deployment region. This affects:

- **Latency**: Choose a region close to your users
- **Compliance**: Select based on data residency requirements
- **Performance**: Consider where your external services are hosted

</Step>

<Step title="Complete App Creation">

After filling in all the configuration details, click **Create App**. Hypermode
then automatically:

1. Sets up your app infrastructure
2. Configures the GitHub integration
3. Generates your app's endpoint and API key
4. Prepares your development environment

</Step>

<Step title="Review your App configuration">

Once created, you'll see your app's configuration panel:

<img
src="/images/apps/console-app.png"
alt="App details panel showing endpoint, GitHub repository, and API key information"
/>

Your new app includes:

### Endpoint

Your production GraphQL endpoint where your app is accessible:

```text
https://your-app-name-workspace-id.hypermode.app/graphql
```

### GitHub repository

The connected repository for automatic deployments. Any push to the main branch
triggers a deployment.

### API key

Your authentication key for accessing the app's API. Keep this secure and use it
in your app headers:

```bash
Authorization: Bearer YOUR_API_KEY
```

</Step>

</Steps>

## Development Approaches

With your app created, you can choose between two development approaches:

### Code first development

- Use the Modus CLI locally
- Full control over app structure
- Traditional Git workflows
- See the [Develop guide](/apps/develop-app) for setup instructions

### Conversational development

- Use Threads for AI-assisted development
- Natural language app building
- Rapid prototyping and iteration
- See the Threads documentation for details

## Next steps

Now that your app is created:

1. **Set up local development** with `modus dev` (see
[Develop guide](/apps/develop-app))
2. **Configure connections** to external services (see
[Connect Your App guide](/apps/connect-app))
3. **Deploy your first version** by pushing to your repository (see
[Deploy guide](/apps/deploy-app))

Your app is now ready for development. The GitHub integration is configured,
your endpoint is live, and you have everything needed to start building your
AI-powered app.

## Troubleshooting

**Repository not appearing in dropdown?**

- Ensure you have proper permissions to the repository
- Check that the Hypermode GitHub App is installed on your organization/account

**App creation failed?**

- Verify your repository is accessible
- Ensure the app name doesn't conflict with existing apps
- Check that all required fields are filled correctly

**Need to change configuration?**

- Most settings can be updated later in the app's configuration panel
- Repository connections can be modified in the app settings
Loading