> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/get-convex/convex-backend/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with self-hosted Convex in minutes

Get your self-hosted Convex instance running quickly with Docker.

## Prerequisites

* [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed
* Node.js 18 or later (for the Convex CLI)

## Quick start

<Steps>
  <Step title="Download docker-compose.yml">
    Create a new directory and download the Docker Compose configuration:

    ```bash theme={null}
    mkdir convex-backend && cd convex-backend
    curl -O https://raw.githubusercontent.com/get-convex/convex-backend/main/self-hosted/docker/docker-compose.yml
    ```

    Or create a `docker-compose.yml` file with this content:

    ```yaml docker-compose.yml theme={null}
    version: '3.8'
    services:
      backend:
        image: ghcr.io/get-convex/convex-backend:latest
        ports:
          - "3210:3210"  # Backend
          - "3211:3211"  # HTTP actions
        environment:
          - CONVEX_SITE_PROXY=http://dashboard:5173
        volumes:
          - convex-data:/data
      
      dashboard:
        image: ghcr.io/get-convex/convex-dashboard:latest
        ports:
          - "6791:5173"
        environment:
          - VITE_SELF_HOSTED_URL=http://localhost:3210

    volumes:
      convex-data:
    ```
  </Step>

  <Step title="Start the services">
    Launch the backend and dashboard:

    ```bash theme={null}
    docker compose up
    ```

    Wait for both services to start. You should see logs indicating the backend is ready.
  </Step>

  <Step title="Generate an admin key">
    In a new terminal, generate an admin key for the CLI:

    ```bash theme={null}
    docker compose exec backend ./generate_admin_key.sh
    ```

    Save the generated admin key - you'll need it in the next step.
  </Step>

  <Step title="Configure your environment">
    Create a `.env.local` file in your Convex project directory:

    ```bash .env.local theme={null}
    CONVEX_SELF_HOSTED_URL=http://127.0.0.1:3210
    CONVEX_SELF_HOSTED_ADMIN_KEY=your-admin-key-here
    ```

    <Warning>
      Never commit this file to version control. Add it to your `.gitignore`.
    </Warning>
  </Step>

  <Step title="Install the Convex CLI">
    Install the latest Convex CLI in your project:

    <CodeGroup>
      ```bash npm theme={null}
      npm install convex@latest
      ```

      ```bash yarn theme={null}
      yarn add convex@latest
      ```

      ```bash pnpm theme={null}
      pnpm add convex@latest
      ```
    </CodeGroup>
  </Step>

  <Step title="Deploy your functions">
    Start the development server to deploy your Convex functions:

    ```bash theme={null}
    npx convex dev
    ```

    This will:

    * Push your schema and functions to the backend
    * Generate TypeScript types
    * Watch for changes and hot-reload
  </Step>

  <Step title="Access the dashboard">
    Open your browser and navigate to:

    ```
    http://localhost:6791
    ```

    You can view your tables, run queries, and monitor your deployment.
  </Step>
</Steps>

## Verify your setup

Create a simple function to test your setup. In your `convex/` directory, create `messages.ts`:

```typescript convex/messages.ts theme={null}
import { query, mutation } from "./_generated/server";
import { v } from "convex/values";

export const list = query({
  handler: async (ctx) => {
    return await ctx.db.query("messages").collect();
  },
});

export const send = mutation({
  args: { body: v.string(), author: v.string() },
  handler: async (ctx, { body, author }) => {
    await ctx.db.insert("messages", { body, author });
  },
});
```

Run the mutation from your app or the dashboard:

```typescript theme={null}
const messageId = await convex.mutation(api.messages.send, {
  body: "Hello, Convex!",
  author: "Test User"
});
```

## What's next?

<CardGroup cols={2}>
  <Card title="Configure your database" icon="database" href="/self-hosting/database-setup">
    Set up PostgreSQL or MySQL for production
  </Card>

  <Card title="Configure storage" icon="server" href="/self-hosting/storage">
    Use S3-compatible storage for files
  </Card>

  <Card title="Explore features" icon="book" href="/features/database">
    Learn about database operations and queries
  </Card>

  <Card title="Build from source" icon="code" href="/development/building-from-source">
    Compile the backend yourself
  </Card>
</CardGroup>

## Troubleshooting

<Accordion title="Backend won't start">
  Check that ports 3210 and 3211 are not already in use:

  ```bash theme={null}
  lsof -i :3210
  lsof -i :3211
  ```

  Stop any conflicting services or change the ports in docker-compose.yml.
</Accordion>

<Accordion title="Can't connect to backend">
  Verify the backend is running:

  ```bash theme={null}
  curl http://localhost:3210/version
  ```

  If this fails, check the Docker logs:

  ```bash theme={null}
  docker compose logs backend
  ```
</Accordion>

<Accordion title="Admin key not working">
  Regenerate the admin key:

  ```bash theme={null}
  docker compose exec backend ./generate_admin_key.sh
  ```

  Update your `.env.local` file with the new key.
</Accordion>

## Support

For self-hosting questions:

* Join the `#self-hosted` channel on [Discord](https://discord.gg/convex)
* Check [GitHub Issues](https://github.com/get-convex/convex-backend/issues)
* Review the [self-hosting documentation](/self-hosting/overview)