Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.matterai.so/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through deploying MatterAI in your own infrastructure using Docker Compose, which is ideal for smaller deployments or testing environments.

​
Prerequisites

You need to have private registery docker credentials. Contact MatterAI team at support@matterai.so
  • A server with Docker and Docker Compose installed
  • GitHub App credentials (see Create Your Own GitHub App)
  • Minimum system requirements:
    • 1 CPU cores
    • 2GB RAM
    • 10GB storage
  • Domain name with SSL certificate (for webhook endpoints)

​
Step 1: Download the docker-compose repository

git clone https://github.com/MatterAIOrg/docker-compose.git
Sample Docker Compose file: 
version: '3.8'

services:
  matter-backend:
    image: gravitycloud/matter-enterprise:latest
    container_name: matter-backend
    restart: always
    ports:
      - "8080:8080"
    environment:
      - EMAIL_DOMAIN=b.com
      - POSTGRES_HOST=localhost
      - POSTGRES_PORT=5432
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    depends_on:
      - postgres
    networks:
      - matter-network
    extra_hosts:
      - "host.docker.internal:host-gateway"
      - "localhost:host-gateway"
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

  matter-frontend:
    image: gravitycloud/matter-frontend:latest
    container_name: matter-frontend
    restart: always
    ports:
      - "80:3000"
    volumes:
      - ./config/nginx.conf:/etc/nginx/conf.d/default.conf
    depends_on:
      - matter-backend
    networks:
      - matter-network
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

  postgres:
    image: postgres:latest
    container_name: postgres-matter
    restart: always
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_DB=postgres
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - matter-network
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 256M

networks:
  matter-network:
    driver: bridge

volumes:
  postgres-data:

​
Step 2: Configure Proxy for Backend APIs (Default works, no Change needed)

This nginx proxy is used to enables routing to backend APIs via frontend security. Here’s the default Nginx configuration: 
server {
  listen 3000;
  server_name localhost;
  root /usr/share/nginx/html;
  index index.html;

  location / {
      try_files $uri $uri/ /index.html;
  }

  location /config/config.js {
      add_header Content-Type application/javascript;
      add_header Cache-Control no-cache;
      return 200 'window.MATTER_CONFIG = {
          BACKEND_URL: "/api"
      };';
  }

  location /api {
    rewrite ^/api/(.*) /$1 break;
    proxy_pass http://matter-backend:8080;

    proxy_set_header Host $http_host;

    proxy_set_header X-Real-IP $remote_addr;

    proxy_set_header X-Forwarded-Proto $scheme;

    proxy_pass_request_headers on;

    proxy_method $request_method;

    proxy_pass_request_body on;

    proxy_set_header X-Original-URI $request_uri;

    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_set_body $request_body;

    proxy_buffering off;
  }

  error_page 404 /index.html;
  add_header X-Frame-Options "SAMEORIGIN";
  add_header X-XSS-Protection "1; mode=block";
  add_header X-Content-Type-Options "nosniff";
}

​
Step 3: Deploy MatterAI

docker compose up -d

​
Step 4: Visit the UI and create a new account

  • Access the MatterAI web interface at http://your-domain.com
  • Access the MatterAI backend at http://your-domain.com/api

​
Maintenance and Updates

​
Updating MatterAI

To update to the latest version of MatterAI: 
# Pull the latest images
docker-compose pull

# Restart the services with the new images
docker-compose up -d

​
Backup and Restore

It’s recommended to regularly backup your PostgreSQL database: 
# Backup
docker-compose exec postgres pg_dump -U ${POSTGRES_USER} ${POSTGRES_DB} > matter_ai_backup_$(date +%Y%m%d).sql

# Restore
cat your_backup_file.sql | docker-compose exec -T postgres psql -U ${POSTGRES_USER} ${POSTGRES_DB}

​
Troubleshooting

​
Common Issues

  1. Webhook not receiving events
    • Verify your webhook URL is correctly configured in your GitHub App
    • Check that your server is accessible from the internet
    • Ensure your SSL certificate is valid
  2. Database connection issues
    • Check the PostgreSQL logs: docker-compose logs postgres
    • Verify the database credentials in your .env file
  3. API service not starting
    • Check the API logs: docker-compose logs api
    • Verify all required environment variables are set correctly

​
Next steps

Configure MatterAI

Configure MatterAI for your enterprise deployment