mirror of
https://github.com/hatchet-dev/hatchet.git
synced 2026-05-03 07:59:31 -05:00
docs: make docs more cli-centric (#2810)
This commit is contained in:
abelanger5
@@ -6,15 +6,19 @@ export default {
|
||||
index: "🪓 Welcome",
|
||||
architecture: "Architecture",
|
||||
"guarantees-and-tradeoffs": "Guarantees & Tradeoffs",
|
||||
"hatchet-cloud-quickstart": "Hatchet Cloud Quickstart",
|
||||
"--quickstart": {
|
||||
title: "Quickstart",
|
||||
type: "separator",
|
||||
},
|
||||
"hatchet-cloud-quickstart": "Hatchet Cloud Quickstart",
|
||||
"--guide": {
|
||||
title: "Walkthrough",
|
||||
type: "separator",
|
||||
},
|
||||
setup: "Setup",
|
||||
"your-first-task": "Tasks",
|
||||
workers: "Workers",
|
||||
"running-your-task": "Running Tasks",
|
||||
"running-your-task": "Your First Task",
|
||||
environments: "Environments",
|
||||
"--running-tasks": {
|
||||
title: "Ways of Running Tasks",
|
||||
|
||||
@@ -8,65 +8,15 @@ When multiple developers share a single Hatchet orchestrator, conflicts can aris
|
||||
|
||||
Hatchet provides three key solutions for managing this challenge: namespaces, multi-tenancy, and a local Hatchet instance.
|
||||
|
||||
### Solution 1: Namespaces
|
||||
### Solution 1: Multi-Tenancy
|
||||
|
||||
Namespaces provide isolation within a single tenant, allowing multiple developers to work simultaneously without conflicts.
|
||||
The easiest way to isolate environments for different developers or teams is to use Hatchet's multi-tenancy feature. Each tenant represents a separate environment with its own set of workflows and workers. To add a new tenant for each developer, create an organization and follow these steps:
|
||||
|
||||
1. **Set a unique namespace** for each developer:
|
||||
|
||||
```bash
|
||||
export HATCHET_CLIENT_NAMESPACE="dev-alice"
|
||||
```
|
||||
|
||||
2. With unique namespaces, developers can work independently:
|
||||
- Workflows only trigger for the namespace that created them
|
||||
- Events remain isolated to their originating namespace
|
||||
- Workers only process jobs from their assigned namespace
|
||||
|
||||
### Solution 2: Multi-Tenancy
|
||||
|
||||
For stronger isolation, create separate tenants for each developer or environment:
|
||||
|
||||
<iframe
|
||||
className="aspect-video w-full my-4"
|
||||
src="https://www.youtube.com/embed/r9NY_nqvqig?si=8cmpM94uYm43jqJI"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowFullScreen
|
||||
/>
|
||||
|
||||
1. Access the tenant dropdown in the dashboard (bottom left)
|
||||
2. Select "Add New Tenant" and provide a descriptive name
|
||||
1. Access the organization dropdown in the dashboard (top right)
|
||||
2. Select the `+` icon next to your organization's name
|
||||
3. Generate a new token for that tenant
|
||||
4. Each developer configures their environment with their designated tenant token
|
||||
|
||||
### Solution 3: Local Hatchet Instance
|
||||
### Solution 2: Local Hatchet Instance
|
||||
|
||||
If you are using Hatchet locally, you can create a local instance of Hatchet to manage your isolated local development environment. Follow instructions [here](../self-hosting/hatchet-lite.mdx) to get started.
|
||||
|
||||
### Recommended Setups
|
||||
|
||||
**For Development Teams:**
|
||||
|
||||
- **Small teams:** Use namespaces within a shared development tenant
|
||||
- **Larger teams:** Leverage local hatchet instances to create separate tenants for each developer
|
||||
- **Production/staging:** Use dedicated tenants with controlled access
|
||||
|
||||
**Implementation Example:**
|
||||
|
||||
```
|
||||
Dev Team Setup:
|
||||
- Central Hatchet Instance
|
||||
├── Tenant: development
|
||||
│ ├── Namespace: dev-alice
|
||||
│ ├── Namespace: dev-bob
|
||||
│ └── Namespace: dev-charlie
|
||||
├── Tenant: staging
|
||||
└── Tenant: production
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Unique Identifiers:** Use consistent, unique identifiers for namespaces and tenants
|
||||
- **Environment Variables:** Set namespace variables in your local environment or .env files
|
||||
- **Token Security:** Treat tenant tokens as sensitive data and avoid sharing them
|
||||
- **Coordination:** Establish naming conventions and communicate among team members to avoid conflicts
|
||||
|
||||
@@ -19,19 +19,69 @@ If you haven't already signed up for Hatchet Cloud, please register [here](https
|
||||
|
||||
In Hatchet Cloud, you'll be shown a screen to create your first tenant. A tenant is a logical separation of your environments (e.g. `dev`, `staging`, `production`). Each tenant has its own set of users who can access it.
|
||||
|
||||
After creating your tenant, navigate to your Hatchet dashboard and navigate to your settings tab. You should see a section called "API Keys". Click "Create API Key", input a name for the key and copy the key. Place the following in a `.env` file:
|
||||
After creating the tenant, you can simply follow the instructions in the Hatchet Cloud dashboard to set up your first quickstart project and workflow. We have copied the instructions in the following steps.
|
||||
|
||||
### Install the Hatchet CLI
|
||||
|
||||
<Tabs items={['Native Install (Recommended)', 'Homebrew']}>
|
||||
<Tabs.Tab value="script" label="Native Install (Recommended)">
|
||||
|
||||
**MacOS, Linux, WSL**
|
||||
|
||||
```sh
|
||||
curl -fsSL https://install.hatchet.run/install.sh | bash
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
<Tabs.Tab value="homebrew" label="Homebrew">
|
||||
|
||||
**MacOS**
|
||||
|
||||
```sh
|
||||
brew install hatchet-dev/hatchet/hatchet --cask
|
||||
```
|
||||
</Tabs.Tab>
|
||||
|
||||
</Tabs>
|
||||
|
||||
### Set your Hatchet profile
|
||||
|
||||
You will need to create a Hatchet CLI profile to connect to your Hatchet Cloud tenant. You can do this using the `hatchet profile add` command:
|
||||
|
||||
```sh
|
||||
HATCHET_CLIENT_TOKEN="<your-api-key>"
|
||||
hatchet profile add
|
||||
```
|
||||
|
||||
<Callout type="info" emoji="💡">
|
||||
The Python SDK uses [Pydantic
|
||||
Settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/) to
|
||||
manage configuration, which will automatically try to load environment
|
||||
variables from a `.env` file, if one is present.
|
||||
</Callout>
|
||||
Note that the Hatchet Cloud dashboard will provide you with an API token to use when creating your profile.
|
||||
|
||||
That's it! You've successfully set up your first Hatchet tenant and are ready to run your first workflow.
|
||||
### Run the quickstart
|
||||
|
||||
You can run the Hatchet Cloud quickstart using the `hatchet quickstart` command:
|
||||
|
||||
```sh
|
||||
hatchet quickstart
|
||||
```
|
||||
|
||||
### Run your worker
|
||||
|
||||
After setting up the quickstart project, you can run your worker locally by following the instructions printed after the quickstart command. This will involve using the `hatchet worker dev` command:
|
||||
|
||||
```sh
|
||||
hatchet worker dev
|
||||
```
|
||||
|
||||
### Trigger a workflow
|
||||
|
||||
Finally, you can trigger your workflow using the `hatchet trigger simple` command:
|
||||
|
||||
```sh
|
||||
hatchet trigger simple
|
||||
```
|
||||
|
||||
</Steps>
|
||||
|
||||
And that's it! You should now have a Hatchet project set up on Hatchet Cloud with a worker running locally.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Once you've completed the quickstart, you can explore a more in-depth walkthrough of Hatchet using the [walkthrough](/home/setup) guide.
|
||||
|
||||
@@ -1,12 +1,18 @@
|
||||
import Tabs from "../_setup/tabs.mdx";
|
||||
import { Callout } from "nextra/components";
|
||||
|
||||
# Get Started with Hatchet
|
||||
# Hatchet Walkthrough
|
||||
|
||||
This guide will help you get started with Hatchet, at the end of the guide you will have a Hatchet project with a basic task and a worker to execute the task.
|
||||
<Callout type="info">
|
||||
This guide is intended for users who want to explore Hatchet in more depth
|
||||
beyond the quickstart. If you haven't already set up Hatchet, please see the
|
||||
[Hatchet Cloud Quickstart](./hatchet-cloud-quickstart) or the [Self-Hosting
|
||||
Quickstart](../../self-hosting/) first.
|
||||
</Callout>
|
||||
|
||||
## Set environment variables
|
||||
|
||||
All Hatchet SDKs require the `HATCHET_CLIENT_TOKEN` environment variable to be set. This token is used to authenticate your requests to the Hatchet API. You can generate an API token from the Hatchet frontend by navigating to the `Settings` tab and clicking on the `API Tokens` tab. Click the `Generate API Token` button to create a new token. Set this environment variable in your project, and **do not share it publicly**.
|
||||
All Hatchet SDKs require the `HATCHET_CLIENT_TOKEN` environment variable to be set. This token is automatically created when you run a CLI command like `hatchet worker dev` or `hatchet trigger`, but if you're setting up a project manually, you'll need to set this variable yourself. You can generate an API token from the Hatchet frontend by navigating to the `Settings` tab and clicking on the `API Tokens` tab. Click the `Generate API Token` button to create a new token. Set this environment variable in your project, and **do not share it publicly**.
|
||||
|
||||
```bash copy
|
||||
export HATCHET_CLIENT_TOKEN="<your-client-token>"
|
||||
|
||||
@@ -13,7 +13,16 @@ This deployment requires [Docker](https://docs.docker.com/engine/install/) insta
|
||||
|
||||
### Getting Hatchet Lite Running
|
||||
|
||||
<Tabs items={['With Postgres (Default)', 'With Postgres + RabbitMQ']}>
|
||||
<Tabs items={['Hatchet CLI', 'With Postgres (Default)', 'With Postgres + RabbitMQ']}>
|
||||
<Tabs.Tab>
|
||||
The easiest way to get Hatchet Lite running is via the Hatchet CLI. Simply run the following command:
|
||||
|
||||
```sh
|
||||
hatchet server start
|
||||
```
|
||||
|
||||
</Tabs.Tab>
|
||||
|
||||
<Tabs.Tab>
|
||||
To use Postgres as both your DB and message queue, copy the following `docker-compose.hatchet.yml` file to the root of your repository:
|
||||
|
||||
@@ -173,24 +182,6 @@ Email: admin@example.com
|
||||
Password: Admin123!!
|
||||
```
|
||||
|
||||
## Run tasks against the Hatchet instance
|
||||
|
||||
To run tasks against this instance, you will first need to create an API token for your worker. There are two ways to do this:
|
||||
|
||||
1. **Using a CLI command**:
|
||||
|
||||
You can run the following command to create a token:
|
||||
|
||||
```sh
|
||||
docker compose -f docker-compose.hatchet.yml exec hatchet-lite /hatchet-admin token create --config /config --tenant-id 707d0855-80ab-4e1f-a156-f1c4546cbf52 | xargs
|
||||
```
|
||||
|
||||
2. **Using the Hatchet dashboard**:
|
||||
- Log in to the Hatchet dashboard.
|
||||
- Navigate to the "Settings" page.
|
||||
- Click on the "API Tokens" tab.
|
||||
- Click on "Create API Token".
|
||||
|
||||
Now that you have an API token, see the guide [here](https://docs.hatchet.run/home/setup) for how to run your first task.
|
||||
After logging in, follow the steps in the UI to create your first tenant and run your first workflow!
|
||||
|
||||
</Steps>
|
||||
|
||||
@@ -16,6 +16,12 @@ Your **workers** (the processes that execute your workflow steps) will connect t
|
||||
|
||||
## Deployment Options
|
||||
|
||||
The fastest way to get a Hatchet instance running locally is with the [Hatchet CLI](/cli) (which wraps Hatchet Lite):
|
||||
|
||||
```sh
|
||||
hatchet server start
|
||||
```
|
||||
|
||||
There are currently three supported ways to self-host the Hatchet Control Plane:
|
||||
|
||||
Docker:
|
||||
|
||||
Reference in New Issue
Block a user