Your First Instance

This guide explains what happens when you provision an OpenBoxes instance, how to access it, and how to complete the initial configuration so your team can start working.

What Provisioning Does

When you click Create Instance in the portal, the platform runs through an automated setup process:

  1. Validation -- Confirms your subdomain is available and your account is in good standing
  2. Database creation -- Sets up an isolated database for your organization's data
  3. Data initialization -- Installs the full OpenBoxes schema, including all tables for products, inventory, stock movements, purchasing, and reporting
  4. Admin account creation -- Creates your administrator account with the credentials linked to your portal login
  5. Subdomain activation -- Configures your custom URL so your instance is reachable at https://your-subdomain.openboxes.cloud

Throughout this process, the portal dashboard shows a progress indicator with the current step.

How Long Does It Take?

Plan Typical Provisioning Time
Shared 1 to 3 minutes
Dedicated 3 to 5 minutes
Enterprise Coordinated with your account team

Dedicated instances take longer because the platform provisions isolated compute resources in addition to the database. You will receive an email notification when your instance is ready.

Accessing Your Instance

From the Portal

The easiest way to access OpenBoxes is through the portal:

  1. Log in at app.openboxes.cloud.
  2. On the dashboard, click Launch OpenBoxes.
  3. You are automatically signed in through SSO. No additional login is required.

Direct URL Access

You can also go directly to your instance URL:

https://your-subdomain.openboxes.cloud

If you are already logged into the portal in the same browser, SSO will sign you in automatically. Otherwise, you will be redirected to the login page.

Bookmark your instance URL for quick access.

The Admin Account

Your initial admin account is created automatically during provisioning. It uses the same email and credentials as your portal account, connected through SSO.

As the admin, you have full access to:

  • All OpenBoxes modules and features
  • User management within OpenBoxes
  • System configuration and location setup
  • Data import and export tools

Initial Configuration

Before your team starts using OpenBoxes, complete these essential setup steps.

Step 1: Create Your First Location

A location in OpenBoxes represents a physical site -- a warehouse, distribution center, clinic, or storage facility. You need at least one location before you can manage inventory.

  1. Click the gear icon in the top navigation bar and select Locations.
  2. Click Create Location.
  3. Fill in the required fields:
    • Name -- A recognizable name (e.g., "Main Warehouse", "Nairobi Depot")
    • Location type -- Select the type that matches your facility (Warehouse, Depot, Supplier, etc.)
    • Organization -- Your organization name
  4. Click Save.

After creating the location, select it from the location selector in the top navigation bar to make it your active location.

Step 2: Configure Location Details

With your location selected, add additional details:

  • Address -- Street address for shipping and receiving documents
  • Supported activities -- Enable the activities relevant to this location (e.g., Manage Inventory, Send Stock, Receive Stock, Putaway Stock)
  • Bin locations (optional) -- If your warehouse uses zones, aisles, or bin locations, you can set these up under the location's configuration

Step 3: Review System Settings

Navigate to Administration > Settings to review default system options:

  • Default currency -- Set to your primary operating currency
  • Date format -- Choose the format your team is accustomed to
  • Locale -- OpenBoxes supports multiple languages

Step 4: Add Products

Your instance starts with an empty product catalog. You can add products in two ways:

  • Manually -- Go to Products > Create Product and enter product details one at a time. This works well for small catalogs or when getting started.
  • Import -- Use the bulk import feature to load products from a spreadsheet. See Migrating Data for a full walkthrough.

At minimum, each product needs a name, a product code, and a category.

Step 5: Invite Your Team

Return to the OpenBoxes Lift portal and invite team members from the Team page. Each person will receive an email invitation to create their account. Once they sign in, they can access your OpenBoxes instance through SSO.

See Account Setup for details on roles and permissions.

Understanding Instance Status

Your portal dashboard shows the current status of your instance:

Status Meaning
Provisioning Setup is in progress. Usually takes a few minutes.
Active Your instance is running and accessible.
Maintenance A scheduled update is being applied. Access may be briefly interrupted.
Suspended Billing issue. Update your payment method to restore access.

Next Steps