Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:

Docker

Docker Engine 20.10+ or Docker DesktopDownload Docker

Docker Compose

Docker Compose v2.0+ (included with Docker Desktop)Install Compose
System Requirements: At least 4GB RAM and 10GB free disk space for all containers.

​
Installation Steps

1

Clone the Repository

Clone the AmbioSys source code to your local machine:
git clone https://github.com/ambiotec/ambiosys.git
cd ambiosys
The repository structure includes:
ambiosys/
├── Backend/
│   ├── web-ambiotec/      # Main API service
│   └── gpt4-ambiotec-bot/ # WhatsApp bot service
├── Frontend/              # React application
├── DB/                    # Database schemas and migrations
└── docker-compose.yml     # Container orchestration
2

Configure Environment Variables

Create environment files for each service. Start with the backend API:
Backend/web-ambiotec/.env
# Database Configuration
PG_HOST=your-postgres-host
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=your-password
PG_DATABASE_AMBIOTEC=ambiotec_db
PG_SEARCH_PATH=db_ambiotec

# Redis Configuration
REDIS_HOST=redis
REDIS_PORT=6379

# API Configuration
API_HOST=localhost
API_PORT=3000
NODE_ENV=development

# Session Secret
SESSION_SECRET=your-random-secret-key

# JWT Authentication
JWT_SECRET=your-jwt-secret
JWT_EXPIRES_IN=24h

# AWS S3 (Optional - for file uploads)
AWS_ACCESS_KEY_ID=your-aws-key
AWS_SECRET_ACCESS_KEY=your-aws-secret
AWS_REGION=us-east-1
AWS_S3_BUCKET=ambiotec-files

# Email Configuration (Optional)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=[email protected]
SMTP_PASSWORD=your-app-password

# OpenAI (for AI features in backend)
OPENAI_API_KEY=your-openai-key
Create Backend/gpt4-ambiotec-bot/.env:
# API Configuration
API_WSPP_HOST=localhost
API_WSPP_PORT=4500
NODE_ENV=development

# Database (shared with main backend)
PG_HOST=your-postgres-host
PG_PORT=5432
PG_USER=postgres
PG_PASSWORD=your-password
PG_DATABASE=ambiotec_db

# Redis
REDIS_HOST=redis
REDIS_PORT=6379

# OpenAI Configuration
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL=gpt-4

# WhatsApp Business API
WHATSAPP_API_TOKEN=your-meta-token
WHATSAPP_VERIFY_TOKEN=your-verify-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
Create Frontend/.env:
# API Endpoints
VITE_API_URL=http://localhost:3000
VITE_WSPP_API_URL=http://localhost:4500

# Socket.IO
VITE_SOCKET_URL=http://localhost:4500

# Environment
VITE_ENV=development
3

Set Up the Database

AmbioSys requires a PostgreSQL database. You can either:Option A: Use an External PostgreSQL InstanceRun the database schema creation script:
psql -h your-host -U postgres -d ambiotec_db -f DB/DDL/DDL.sql
Then run migrations:
psql -h your-host -U postgres -d ambiotec_db -f DB/Migrations/*.sql
Option B: Add PostgreSQL to Docker Compose (Recommended for development)Add this service to your docker-compose.yml:
postgres:
  image: postgres:15-alpine
  container_name: ambiotec-postgres
  environment:
    POSTGRES_DB: ambiotec_db
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: your-password
  ports:
    - "5432:5432"
  volumes:
    - postgres_data:/var/lib/postgresql/data
    - ./DB:/docker-entrypoint-initdb.d
  networks:
    - ambio_net
And add the volume:
volumes:
  postgres_data:
  redis_data:
  backend_node_modules:
4

Start the Services

Launch all services with Docker Compose:
docker-compose up -d
This will start:
  • Redis on port 6379
  • Backend API on port 3000
  • WhatsApp Bot on port 4500
The frontend is currently commented out in docker-compose.yml. To run it:
cd Frontend
npm install
npm run dev
Access it at http://localhost:5173
5

Verify Installation

Check that all services are running:
docker-compose ps
You should see:
NAME                   STATUS              PORTS
ambiotec-redis        Up 30 seconds       0.0.0.0:6379->6379/tcp
ambiotec-backend      Up 28 seconds       0.0.0.0:3000->3000/tcp
gpt4-ambiotec-bot     Up 27 seconds       0.0.0.0:4500->4500/tcp
Test the backend API:
curl http://localhost:3000
Expected response:
{
  "name": "Ambiotec Backend API",
  "version": "1.0.0",
  "env": "development",
  "uptime": 125.234,
  "status": "ok"
}
Test the WhatsApp bot:
curl http://localhost:4500
Expected response:
{
  "name": "Bot de Ambiotec",
  "version": "1.0.0",
  "env": "development",
  "uptime": 123.456,
  "status": "ok"
}

​
Accessing the Application

Frontend

http://localhost:5173React application with Material-UI

Backend API

http://localhost:3000Express.js REST API

WhatsApp Bot

http://localhost:4500GPT-4 powered bot service

API Documentation

http://localhost:3000/api-docsInteractive Swagger API documentation

​
Default Login Credentials

Change these credentials immediately after first login in production environments!
If you’ve run the database seed scripts, you can log in with:
  • Username: admin
  • Password: Check your database initialization scripts in DB/DML/DML.sql

​
Next Steps

Architecture Overview

Learn how the microservices communicate and the data flow

API Reference

Explore available endpoints and request/response formats

Environment Variables

Deep dive into environment variables and system settings

Database Setup

Set up PostgreSQL database and schemas

​
Troubleshooting

Check Docker logs for errors:
docker-compose logs backend
docker-compose logs gpt4-ambiotec-bot
docker-compose logs redis
Common issues:
  • Port already in use: Change ports in docker-compose.yml
  • Missing .env files: Ensure all environment files are created
  • Insufficient resources: Increase Docker memory allocation
Verify database connectivity:
docker-compose exec backend npm run db:test
Or check PostgreSQL directly:
psql -h localhost -U postgres -d ambiotec_db -c "SELECT NOW();"
Check these settings in your .env:
  • PG_HOST should match your database host
  • PG_PORT (default 5432)
  • PG_USER and PG_PASSWORD
  • PG_DATABASE_AMBIOTEC
Ensure Redis is running:
docker-compose ps redis
Test Redis connectivity:
docker-compose exec redis redis-cli ping
Should return: PONG
Verify CORS settings in Backend/web-ambiotec/src/app.js:
app.use(cors());
Check frontend .env has correct API URL:
VITE_API_URL=http://localhost:3000
The backend uses nodemon for hot-reload. Check volume mounts in docker-compose.yml:
volumes:
  - ./Backend/web-ambiotec:/usr/src/app
  - backend_node_modules:/usr/src/app/node_modules
If changes aren’t detected, restart with:
docker-compose restart backend
For production deployment, see the Docker Setup Guide for environment-specific configurations and best practices.

Build docs developers (and LLMs) love

Get started for freeTalk to us