Getting Started

If you are new to self-hosting Neo, this guide will walk you through the initial setup process. Make sure you have met all the requirements before proceeding.

Step 1: Clone the Repository

If you haven't guessed it yet, the first step is to clone the NeoStack repository to your server. You can do this using Git:

git clone https://github.com/betidestudio/neostack.git

If you want to use stable releases, you can check out a specific tag. For example, to check out version 0.2.0, you would run:

git checkout tags/v0.2.0

Step 2: Set Up Convex Self-Hosted Database

NeoStack requires a Convex database backend. You'll need to set up a self-hosted Convex instance to handle your data storage and real-time functionality.

Download and Start Convex Backend

First, download the Convex self-hosted docker-compose configuration:

curl -O https://raw.githubusercontent.com/get-convex/convex-backend/main/self-hosted/docker/docker-compose.yml

Start the Convex backend and dashboard:

docker compose up -d

This will start:

• Convex backend on http://127.0.0.1:3210
• HTTP actions on http://127.0.0.1:3211
• Dashboard on http://localhost:6791

Generate Admin Key

Generate an admin key for dashboard and CLI access:

docker compose exec backend ./generate_admin_key.sh

Save this admin key - you'll need it for the next step.

Step 3: Configure Environment Variables

Now, set up your environment variables. Start by copying the example environment file:

cp .env.example .env

Open the .env file in your favorite text editor and configure the following variables:

# Convex Self-Hosted Configuration
CONVEX_SELF_HOSTED_URL=http://127.0.0.1:3210
CONVEX_SELF_HOSTED_ADMIN_KEY=your_admin_key_from_previous_step

Make sure to replace your_admin_key_from_previous_step with the actual admin key you generated earlier.

Step 4: Setting up Rust Backend

NeoStack uses a Rust backend for certain functionalities. Ensure you have Rust installed on your system. If you don't have it yet, you can install it using the following command:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installing Rust, navigate to the Rust backend directory and build the project:

cd backend/rust
cargo build --release

This will compile the Rust backend and prepare it for use. Though minor changes are expected, this step is crucial for ensuring that the Rust components are correctly set up.

Step 5: Install Dependencies

Navigate to the NeoStack directory and install the necessary dependencies using npm or yarn:

pnpm install

Step 6: Set Up Convex Schema

Next, set up the Convex schema. Run the following command to push the schema to your Convex backend:

pnpx convex push

Step 7: Configuring API Keys

NeoStack requires API keys for certain functionalities. You can obtain these keys from the respective service providers. Once you have the keys, add them to your .env file:

# Example API Keys
OPENROUTE_API_KEY=your_openroute_api_key
VERCEL_AI_GATEWAY_API_KEY=your_vercel_ai_gateway_api_key
GITHUB_OAUTH_CLIENT_ID=your_github_oauth_client_id
GITHUB_OAUTH_CLIENT_SECRET=your_github_oauth_client_secret
R2_ACCESS_KEY_ID=your_r2_access_key_id
R2_BUCKET_NAME=your_r2_bucket_name
R2_ENDPOINT=your_r2_endpoint
R2_SECRET_ACCESS_KEY=your_r2_secret_access_key
R2_TOKEN=your_r2_token

Step 8: Start the NeoStack Application

Finally, start the NeoStack application:

pnpm dev