From dfbacfd8bbe854af3f4117bc40b92619a7e2af9c Mon Sep 17 00:00:00 2001
From: Daryl Lim <5508348+daryllimyt@users.noreply.github.com>
Date: Mon, 29 Apr 2024 17:34:24 +0100
Subject: [PATCH] docs: Update installation guide for Clerk migration
---
docs/installation.mdx | 106 +++++++++++++++++++++++-------------------
1 file changed, 57 insertions(+), 49 deletions(-)
diff --git a/docs/installation.mdx b/docs/installation.mdx
index 476faad7..2cff0b5d 100644
--- a/docs/installation.mdx
+++ b/docs/installation.mdx
@@ -10,64 +10,69 @@ description: Run Tracecat locally
Install Tracecat locally on your machine.
-## Video Tutorial
-
-
-
## Prerequisites
### Required
- [Docker](https://docs.docker.com/get-docker/)
-- [Docker compose](https://docs.docker.com/compose/install/)
+- [Docker Compose](https://docs.docker.com/compose/install/)
- [ngrok](https://ngrok.com/)
-- [Supabase CLI Tool](https://supabase.com/docs/guides/cli/getting-started)
### Optional
-- [OpenAI API key](https://platform.openai.com/signup)
-- [Resend API Key](https://resend.com/docs/introduction)
+You don't have to set up these services to run Tracecat, but they are required for certain features.
+
+- [OpenAI API key](https://platform.openai.com/signup) (required for AI actions)
+- [Resend API Key](https://resend.com/docs/introduction) (required for Email actions)
-## Start Tracecat
+## Setup
-Please install the prerequisite tools beforehand, then run the command below to start Tracecat and all related services.
+Please install the prerequisite tools beforehand.
+
+Clone the Tracecat repository and navigate to the project root:
```bash
git clone git@github.com:TracecatHQ/tracecat.git
cd tracecat
-chmod +x services.sh
-bash services.sh start --env prod
```
-
- You can run `bash services.sh start --env prod --tail` to view the logs of all
- services in real-time.
-
+### Environment variables
+
+#### Manual
+
+To manually set up environment variables, copy `.env.example` to create a `.env` file.
+
+```bash
+cp .env.example .env
+```
+
+You will have to replace the environment variables prefixed with `your-.*` with your own values.
+
+#### Using `env.sh` (recommended)
+
+The `env.sh` script runs commands to set up the database encryption key, API service key, and webhook signing secret for you.
-You'll be prompted to enter your public facing Runner URL (you can set one up using ngrok), OpenAI API key, and Resend API key.
-If you use ngrok, the Runner URL should take the form `https://.ngrok-free.app`.
-See the section [Export runner via ngrok](#expose-runner-via-ngrok) for more details.
+Run the following command to create a `.env` file in the root directory:
+```bash
+chmod +x env.sh
+bash env.sh
+```
+
+You'll be prompted to enter your public facing Runner URL, OpenAI API key, and Resend API key.
If you'd rather provide these later, you can skip each prompt step by pressing `Enter`.
-You can update the `.env` file in the root directory then run `bash services.sh start` again to restart the services.
-## Expose runner via ngrok
+If you use `ngrok`, the Runner URL should take the form `https://.ngrok-free.app`.
+See the section [Expose runner via ngrok](#expose-runner-via-ngrok) for more details.
+
+### Expose runner via ngrok
Go to [ngrok](https://ngrok.com/) and create an account.
Follow the instructions in [getting started](https://dashboard.ngrok.com/get-started/setup) to install `ngrok` on your local machine.
Then, go to [ngrok dashboard](https://dashboard.ngrok.com/cloud-edge/domains) and create a new domain (you get 1 free static domain).
The domain should be in the format `.ngrok-free.app`.
-For example, if your ngrok domain is `your-grnok-domain.ngrok-free.app`, start ngrok by running the following command:
+For example, if your ngrok domain is `your-grnok-domain.ngrok-free.app`, start `ngrok` by running the following command:
```bash
ngrok http --domain=your-ngrok-domain.ngrok-free.app 8001
@@ -80,8 +85,8 @@ ngrok http http://localhost:8001
```
- Binding ngrok to port 8001 on the host machine forwards the runner server to
- the internet and enables incoming webhooks.
+ By binding `ngrok` to port 8001 on the host machine, incoming webhook requests
+ are forwarded to the Runner container.
If correctly set up, your .env should contain:
@@ -90,15 +95,19 @@ If correctly set up, your .env should contain:
TRACECAT__RUNNER_URL=https://your-ngrok-domain.ngrok-free.app
```
-## Create user
+### Start Tracecat services
-Go to the Supabase dashboard at `http://localhost:54323`, navigate to the authentication tab, and create a new user.
+Finally, start Tracecat using `docker compose`:
+
+```bash
+docker compose up
+```
## Access Tracecat
The Tracecat frontend should now be running on port `3000`.
To access the frontend, open your browser and navigate to `http://localhost:3000`.
-Sign-in with the user you created in Supabase.
+You do not need to create an account for local usage.
Tracecat's API and runner servers are also accessible via ports `8000` and `8001`, respectively.
You can view the API docs at `http://localhost:8000/docs` and the runner docs at `http://localhost:8001/docs`.
@@ -115,24 +124,23 @@ You can view the API docs at `http://localhost:8000/docs` and the runner docs at
To spin down all services, run the following command:
```bash
-bash services.sh stop --env prod
+docker compose down --remove-orphans
```
-If you'd like to spin down specific services, you can pass additional options as such:
+## Authentication
-```bash
-bash services.sh stop --internal # or -i, Stops all Tracecat internal services
-bash services.sh stop --supabase # or -s, Stops Supabase services
-```
-
-## Restarting services
+So far, we've shown how to run Tracecat locally without authentication and runnning with a default user.
-Running `bash services.sh start` will restart all services if they are already running.
+If you want to enable authentication, you can set the `TRACECAT__DISABLE_AUTH` environment variable to `false` or `0` in the `.env` file. This requires you to have a Clerk account and set up the Clerk environment variables in `.env`.
-## Runtime environment configuration
-
-Note that we've been passing `--env prod` flag to the `services.sh` script. This is to avoid having to install `npm` and `pnpm` on the host machine.
-If you'd like to make code contributions or run the services in development mode, use `--env dev` instead or don't pass an environment flag (runs as `dev` by default).
+```bash
+# --- Authentication + Clerk ---
+TRACECAT__DISABLE_AUTH=0
+# Fill these in!
+CLERK_FRONTEND_API_URL=...
+CLERK_SECRET_KEY=...
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=...
+```
## Troubldshooting