This guide walks you through deploying Matter AI 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 Matter AI team at support@matterai.dev

  • 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/GravityCloudAI/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:
      - "3000: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 Matter AI

docker compose up -d

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

Access the Matter AI web interface at http://your-domain.com (or http://localhost:3000 if not using a reverse proxy)

​
Maintenance and Updates

​
Updating Matter AI

To update to the latest version of Matter AI:

# 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 Matter AI

Configure Matter AI for your enterprise deployment