Deployment Guide

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• link.sh
• src/lib/constants.ts
• agent-packages/packages/github/package.json
• agent-packages/packages/common/package.json
• agent-packages/packages/jira/package.json
• agent-packages/packages/slack/package.json

Quix is an AI-powered Slack agent that interacts with various business tools like JIRA, GitHub, and HubSpot directly from Slack. This guide provides comprehensive instructions for setting up the development environment, configuring the application, and deploying it to production. The project is a Nest.js application with a modular monorepo structure, allowing for scalable and maintainable integrations.

This guide covers both local development using yarn and a local database, as well as containerized deployment using Docker. Understanding the project's structure is key to a successful deployment.

Sources: README.md:1-5, 20-36

Project Structure and Dependencies

The Quix project is organized as a monorepo, with the main Nest.js application in the src/ directory and individual integration logic encapsulated in packages within agent-packages/packages/. This modular design promotes separation of concerns and reusability.

Sources: README.md:20-36

The following diagram illustrates the high-level project structure:

This diagram shows the main application depends on the agent packages, which in turn often depend on a common package.
Sources: README.md:20-36, link.sh:15-18

Core Dependencies

The main application relies on several key dependencies defined in package.json.

Dependency	Version	Description
@nestjs/core	^11.0.16	The core framework for the application.
@slack/web-api	^7.8.0	Official Slack Web API client for interacting with Slack.
@langchain/openai	0.5.18	OpenAI integration for LLM capabilities.
sequelize	^6.37.6	ORM for interacting with the PostgreSQL database.
redis	^4.7.0	Redis client for caching.
@clearfeed-ai/quix-*	various	Agent packages for specific integrations (GitHub, JIRA, etc.).

Sources: package.json:44-71

Agent Packages

Each integration (e.g., GitHub, JIRA) is a separate package under agent-packages/packages. These packages are linked to the main application during local development using yarn link. The link.sh script automates this process.

Sources: README.md:100-106, link.sh

Environment Configuration

Before running the application, you must configure environment variables. Copy the example file and populate it with your credentials and settings.

cp .env.example .env

Sources: README.md:50-52

The following variables are required:

Variable	Description
PORT	Server port (default: 3000).
OPENAI_API_KEY	Your OpenAI API key.
SLACK_BOT_TOKEN	Slack bot token obtained from your Slack app settings.
SLACK_SIGNING_SECRET	Slack signing secret from your Slack app settings.
SELFSERVER_URL	Your public domain or ngrok URL for development.
DB_HOST	Database hostname.
DB_PORT	Database port.
DB_USER	Database username.
DB_PASSWORD	Database password.
DB_NAME	Database name.
REDIS_HOST	Redis hostname.
REDIS_PORT	Redis port.

Sources: README.md:54-71

Local Development Setup

This section outlines the steps to run Quix on your local machine for development and testing.

1. Prerequisites

First, clone the repository and install all dependencies using yarn.

git clone <repository-url>
cd quix
yarn install

The yarn install command will install dependencies for both the root project and the individual agent packages.

Sources: README.md:43-48

2. Slack App Configuration

A Slack App is required to interact with Quix. For local development, a tunneling service like ngrok is needed to expose your local server to the internet.

The following diagram shows the setup flow for local development with Slack:

Steps:

1. Start the application in development mode: yarn start:dev.
2. In a new terminal, start ngrok: ngrok http 3000.
3. Create a Slack App using the slack_app_manifest.yml file.
4. Replace the placeholder URLs (<YOUR_EVENTS_URL>, <YOUR_INTERACTIONS_URL>, <YOUR_REDIRECT_URL>) in the manifest with your ngrok URL.
5. Install the app to your workspace and copy the "Bot User OAuth Token" (SLACK_BOT_TOKEN) and "Signing Secret" (SLACK_SIGNING_SECRET) to your .env file.

Sources: README.md:73-98

3. Database Setup

Run the database migrations to set up the required tables.

yarn db:migrate

This command uses sequelize-cli to apply all pending migrations.

Sources: README.md:100-102, package.json:33

4. Running the Application

Once configured, you can start the application in different modes using the scripts defined in package.json.

Script	Description
start:dev	Starts the application in watch mode with hot-reloading.
start:debug	Starts in debug and watch mode.
build	Compiles the TypeScript source to JavaScript in dist/.
start:prod	Starts the compiled application from the dist/ directory.

Sources: package.json:25-28

For local development, use:

yarn start:dev

Sources: README.md:104-106

Production Deployment

For production, the application should be built and run from the compiled JavaScript files.

Build and Run Flow

This diagram shows the process of installing dependencies, building the project, and starting the production server.
Sources: README.md:108-111, package.json:23,28

Steps:

1. Install dependencies: yarn install
2. Build the application: yarn build
3. Start the production server: yarn start:prod

Ensure all environment variables in .env are correctly set for your production environment, especially SELFSERVER_URL, which should point to your public domain.

Sources: README.md:108-111

Docker Deployment

Quix includes support for containerized deployment using Docker. This is a recommended approach for production environments.

Building the Docker Image

You can build a Docker image using the provided Dockerfile.

docker build -t quix .

Sources: README.md:115-116

Running the Docker Container

Run the built image, providing the environment variables via an .env file.

docker run -p 3000:3000 --env-file .env quix

This command maps port 3000 on the host to port 3000 in the container.

Sources: README.md:118-119

Docker Compose for Local Development

For a complete local development environment including services like Redis and Postgres, you can use Docker Compose.

docker-compose -f docker-compose.local.yml up

The docker-compose.local.yml file is specifically configured for local development needs.

Sources: README.md:121-123

Health Check

The application exposes a health check endpoint that can be used to monitor its status.

• Endpoint: GET /health
• Description: Returns a status indicating if the application is running correctly.

Sources: README.md:108