Setup & Installation

Get Orbu up and running in minutes

Local Development Setup

This guide covers running Orbu locally for development and testing purposes.

For production deployment: Use a cloud service or dedicated server with proper security configurations. Deploy using Docker on platforms like AWS, Azure, Google Cloud, DigitalOcean, or your own infrastructure. Ensure you configure firewalls, use secure passwords, enable HTTPS, and follow production security best practices.

Prerequisites

Before installing Orbu, ensure you have the following:

Docker and Docker Compose installed on your system
Git for cloning the repository
Python 3.x (for generating encryption keys during manual setup)
Access to one or more Acumatica instances with REST API enabled

Note: Orbu runs entirely in Docker containers, making installation consistent across Windows, macOS, and Linux.

Quick Start (Automated Setup)

The fastest way to get Orbu running is using the automated setup scripts. Choose your platform:

# Clone repository
git clone https://github.com/Nioron07/Orbu.git
cd Orbu

# Run setup script
.\scripts\setup.ps1

The setup script will automatically:

Check Docker and Docker Compose installation
Create .env file from template
Generate encryption and secret keys
Start all services
Wait for services to be healthy

That's it! Once the script completes, access Orbu at http://localhost:8080

Manual Setup

If you prefer manual control or the automated script doesn't work for your environment, follow these steps:

1. Clone Repository

First, clone the Orbu repository from GitHub:

git clone https://github.com/Nioron07/Orbu.git
cd Orbu

2. Configure Environment

Create your environment file and generate the required encryption keys:

# 1. Create environment file from template
Copy-Item .env.example .env

# 2. Generate encryption keys (saves to .env automatically)
python scripts/generate_keys.py

# 3. Edit .env and change POSTGRES_PASSWORD to a secure password

Important: After running the generate_keys.py script, open the .env file and change POSTGRES_PASSWORD to a secure password of your choice.

Environment Variables

Key environment variables in your .env file:

# Database
POSTGRES_DB=orbu
POSTGRES_USER=orbu
POSTGRES_PASSWORD=your-secure-password

# Encryption (REQUIRED)
ENCRYPTION_KEY=your-fernet-key

# Flask
SECRET_KEY=your-secret-key

Configuration Options

Variable	Description	Required
`POSTGRES_DB`	PostgreSQL database name	Yes
`POSTGRES_USER`	PostgreSQL username	Yes
`POSTGRES_PASSWORD`	PostgreSQL password	Yes
`ENCRYPTION_KEY`	Fernet encryption key for credential storage	Yes
`SECRET_KEY`	Flask secret key for session management	Yes

Security Warning: Keep your .env file secure and never commit it to version control. The encryption key protects sensitive Acumatica credentials stored in the database.

3. Start Services

With configuration complete, start all Orbu services using Docker Compose:

docker compose up -d

4. Verify Services

Check that all services are running correctly:

docker compose ps

You should see four containers running:

orbu-nginx - Nginx reverse proxy (serves frontend and routes API calls)
orbu-backend - Flask API server
orbu-frontend - Vue.js build container
orbu-postgres - PostgreSQL database

Tip: Initial startup may take 2-3 minutes as containers build and the database initializes. Subsequent starts will be much faster.

Access Application

Once all services are running, open your web browser and navigate to:

http://localhost:8080

Default Orbu web interface

You should see the Orbu welcome page. You're now ready to add your first Acumatica client!

Next Steps: Head to the Client Management guide to learn how to connect your first Acumatica instance.

Troubleshooting

View Logs

If you encounter issues, check the container logs:

# View all logs
docker compose logs

View logs for a specific service:

# View logs for a specific service
docker compose logs backend
docker compose logs nginx
docker compose logs postgres

Rebuild Services

If services fail to start or behave unexpectedly, try rebuilding:

# Rebuild and restart
docker compose down
docker compose up -d --build

Common Issues

Service Management

Stop Services

To stop all Orbu services:

docker compose stop

Restart Services

To restart services after stopping:

docker compose up -d

Remove Services

To completely remove all containers and volumes (including database data):

# Remove containers and volumes (deletes all data!)
docker compose down --volumes

Warning: The --volumes flag will delete all database data including saved clients and endpoints. Only use this if you want to completely reset Orbu.

Next Steps

Now that Orbu is installed, you're ready to explore its features:

Client Management

Connect your first Acumatica instance

Browse Services

Explore available REST API services

On this page