Merge 305e424 into 9344abf

quirrel-dev · Jun 20, 2023 · 29a6a38 · 29a6a38
2 parents 9344abf + 305e424
commit 29a6a38
Show file tree

Hide file tree

Showing 13 changed files with 445 additions and 189 deletions.
diff --git a/docs/docs/api/next.md → docs/docs/api/next.mdx b/docs/docs/api/next.md → docs/docs/api/next.mdx
@@ -1,21 +1,44 @@
----
-title: Next.js
----
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
 
-```ts title="pages/api/someQueue.ts"
-import { Queue } from "quirrel/next";
+# Next.js
 
-export default Queue(
-"api/someQueue",
+<Tabs>
+<TabItem value="app" label="App Router">
+
+```typescript title="app/api/queues/sample/route.ts"
+import { Queue } from "quirrel/next-app";
+
+export const sampleQueue = Queue(
+  "api/queues/sample",
   async (job, meta) => {
     // do something
   }
 );
+
+export const POST = sampleQueue;
+```
+
+Creates a new Queue.
+Make sure to export it from a [Route Handler](https://nextjs.org/docs/app/building-your-application/routing/router-handlers), otherwise it won't work.
+
+</TabItem>
+<TabItem value="page" label="Pages Router">
+
+```typescript title="pages/api/queues/sample.ts"
+import { Queue } from "quirrel/next-pages";
+
+export default Queue("api/queues/sample", async (job, meta) => {
+  // do something
+});
 ```
 
 Creates a new Queue.
 Make sure to export it from an [API Route](https://nextjs.org/docs/api-routes/introduction), otherwise it won't work.
 
+</TabItem>
+</Tabs>
+
 #### Parameters
 
 ```ts
@@ -26,6 +49,7 @@ function Queue<T>(
 ): QueueInstance<T>
 ```
 
+
 | Parameter           | Usage                                                           |
 | ------------------- | --------------------------------------------------------------- |
 | `path`              | The route that this queue is reachable at.                      |

diff --git a/docs/docs/deploying.md b/docs/docs/deploying.md
diff --git a/docs/docs/deployment/docker.md b/docs/docs/deployment/docker.md
@@ -0,0 +1,67 @@
+# Docker
+
+Deploying Quirrel in a Docker environment is straightforward and easy. Here are detailed steps including the necessary environment variables, how to build your Docker image and run your Quirrel instance using Docker.
+
+## Docker Deployment
+
+Deploy Quirrel using the official Docker image provided by Quirrel: [Quirrel Docker Image](https://github.com/orgs/quirrel-dev/packages/container/package/quirrel)
+
+1. Pull the official Quirrel Docker image:
+
+```bash
+docker pull ghcr.io/quirrel-dev/quirrel:main
+```
+
+2. Define your environment variables in a `.env` file:
+
+```env
+REDIS_URL=your_redis_url
+PASSPHRASES=your_passphrases
+REDIS_TLS_CA_BASE64=your_base64_encoded_certificate # if applicable
+REDIS_TLS_CA_FILE=your_certificate_file_path # if applicable
+```
+
+3. Run the Docker container, replace `<name_of_your_container>` with your preferred container name:
+
+```bash
+docker run --env-file .env -p 9181:9181 --name <name_of_your_container> ghcr.io/quirrel-dev/quirrel:main
+```
+
+This command will start a new Docker container and expose it on port 9181.
+
+## Token Acquisition
+
+Once your server is ready, [acquire an auth token](https://api.quirrel.dev/documentation/static/index.html#/Admin/put_tokens__id_):
+
+```bash
+curl --user ignored:{PASSPHRASE} -X PUT {QUIRREL_SERVER_URL}/tokens/{NAME_OF_TOKEN}
+```
+
+Replace `{}` placeholders with your actual values. Save the returned token for the next step.
+
+## Connecting Your Application to the Quirrel Deployment
+
+Configure your application to connect to your Quirrel deployment by specifying the following two environment variables:
+
+### Environment Variables
+
+These are the necessary environment variables for your Docker deployment:
+
+| Variable                    | Meaning                                                           | Where to Get It                                                                                                                                                            |
+| --------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `QUIRREL_TOKEN`             | Access token for the Quirrel server                               | Create a new Project + Client in the [Quirrel Dashboard](https://quirrel.dev/dashboard)                                                                                    |
+| `QUIRREL_BASE_URL`          | The base URL of your application's deployment                     | Something like `my-application.com`                                                                                                                                        |
+| `QUIRREL_ENCRYPTION_SECRET` | A 32-character-long secret for end-to-end encryption of your jobs | Generate it using `openssl rand -hex 16` or [random.org](https://www.random.org/strings/?num=2&len=16&digits=on&upperalpha=on&loweralpha=on&unique=on&format=html&rnd=new) |
+| `QUIRREL_API_URL`           | The URL for your Quirrel API endpoint                             | The URL of your Quirrel Docker deployment, usually `http://your-quirrel-api-address:9181`                                                                                  |
+
+## Scripts
+
+If you're using [CronJobs](/api/cronjob), ensure to run `quirrel ci` during the Docker build process. You can include this in your Dockerfile:
+
+```Dockerfile
+RUN npm run build && quirrel ci
+```
+
+## Conclusion
+
+With these settings, you can easily deploy your application with Quirrel in a Docker environment. If you encounter any issues, feel free to reach out to [troubleshooting@quirrel.dev](mailto:troubleshooting@quirrel.dev).
diff --git a/docs/docs/deployment/fly.md b/docs/docs/deployment/fly.md
@@ -0,0 +1,5 @@
+# Fly.io
+
+If you're planning to host your Quirrel instance on Fly.io, you can follow [Mokhtar Mial](https://twitter.com/m5r_m)'s tutorial:
+
+[Self-Hosting Quirrel on Fly.io](https://dev.to/remixtape/self-hosting-quirrel-5af7)
diff --git a/docs/docs/deployment/railway.mdx b/docs/docs/deployment/railway.mdx
@@ -0,0 +1,24 @@
+# Railway
+
+To deploy your own Quirrel server to Railway, click this button:
+
+[![Deploy to Railway](https://railway.app/button.svg)](https://railway.app/new/template/quirrel)
+
+During the process, Railway will clone this repository for you. In there, you find a `Dockerfile`. To pin down your Quirrel version, update its tag:
+
+```diff
+- FROM ghcr.io/quirrel-dev/quirrel:main
++ FROM ghcr.io/quirrel-dev/quirrel:sha-f218c98
+```
+
+Check Quirrel's [Docker image page](https://github.com/quirrel-dev/quirrel/pkgs/container/quirrel) to find the exact version you want to pin.
+
+Use the `PASSPHRASE` you set during the creation to issue a new token:
+
+```sh
+curl --user ignored:<PASSPHRASE> -X PUT https://mighty-owl-production.up.railway.app/tokens/foo
+```
+
+You now have your own Quirrel instance 🥳
+
+Next step: [Connecting your application](https://docs.quirrel.dev/deploying).
diff --git a/docs/docs/deployment/vercel.md b/docs/docs/deployment/vercel.md
@@ -0,0 +1,26 @@
+# Vercel
+
+Deploying your Quirrel powered application on Vercel is an easy process. There are a few environment variables you need to configure, and possibly an additional script depending on your use case.
+
+## Environment Variables
+
+Configure the following environment variables for your Vercel deployment:
+
+| Variable                    | Meaning                                                           | Where to Get It                                                                                                                                                                                                              |
+| --------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `QUIRREL_TOKEN`             | Access token for the Quirrel server                               | Create a new Project + Client in the [Quirrel Dashboard](https://quirrel.dev/dashboard)                                                                                                                                      |
+| `QUIRREL_BASE_URL`          | The base URL of your application's deployment                     | Something like `my-application.com`, you can set `QUIRREL_BASE_URL` to your `VERCEL_URL` for preview environments only. Do not do this for production. Set the value of `QUIRREL_BASE_URL` to `@VERCEL_URL` to achieve this. |
+| `QUIRREL_ENCRYPTION_SECRET` | A 32-character-long secret for end-to-end encryption of your jobs | Generate it using `openssl rand -hex 16` or [random.org](https://www.random.org/strings/?num=2&len=16&digits=on&upperalpha=on&loweralpha=on&unique=on&format=html&rnd=new)                                                   |
+| `QUIRREL_API_URL`           | The URL for your Quirrel API endpoint                             | The URL of your hosted Quirrel server, usually `http://your-quirrel-api-address:9181`                                                                                                                                        |
+
+## Scripts
+
+If you are using [CronJobs](/api/cronjob), ensure to run `quirrel ci` during the deploy process. Configure the `vercel-build` command in your `package.json` file:
+
+```json
+"scripts": { "vercel-build": "npm run build && quirrel ci" }
+```
+
+## Conclusion
+
+By configuring these settings, you can easily deploy your application with Quirrel on Vercel. If you encounter any issues, feel free to reach out to [troubleshooting@quirrel.dev](mailto:troubleshooting@quirrel.dev).
diff --git a/docs/docs/development.mdx b/docs/docs/development.mdx
@@ -0,0 +1,21 @@
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Development
+
+During development, you can use Quirrel's lightweight local server.
+This runs entirely on your machine, without needing any database or other external services.
+
+After installing Quirrel via `npm install quirrel`, the local server is started by running `quirrel` in your terminal.
+This will start a server and automatically start scanning for CronJobs in your project.
+If you're using the default development port of your framework (like `:3000` for Next.js), then Quirrel will automatically detect and use the local server.
+
+You can run `quirrel ui` to open up an admin interface that could be useful in local development.
+
+To always run Quirrel as part of your local development environment, you can add it to your `package.json`:
+
+```json
+"scripts": {
+  "dev": "concurrently 'next dev' 'quirrel'"
+}
+```