Skip to main content
Version: 2.2.0

Dashboard Module Quickstart

Get started with the Dashboard (DASH) module to create and manage interactive dashboards with customizable widgets in your web application.

Prerequisites​

The following section assumes you have installed all the tools required for web development from our tools section.

Before you move on, it is also mandatory that you read through the key technology list in our web technologies section and you understand the justification for each one, especially if you're not familiar with the specific technology.

info

It is presumed that you already have a web-base prepared and ready for you to install modlets, otherwise, please go to the Web-base quickstart section to initialize your web-base.

Alternatively, you can clone the web-base repository:

git clone https://github.com/mssfoobar/web-base.git
cd web-base
npm install

Frontend Setup​

1. Install the DASH Modlet​

Run the following command in the root of your web-base project:

web-base/web/.env
npx cli install dash

You'll be prompted to choose your 'root folder' - use the default (current working directory).

The modlet will be installed with:

  • Dashboard components and widgets
  • Navigation configuration
  • Type definitions and services
  • Dependencies added to your package.json

2. Configure Environment Variables​

Add the required environment variables to your .env file:

web-base/.env
## ==================== DASH ====================
# URL of the dashboard service (required)
DASH_URL=http://dash.127.0.0.1.nip.io
# URL of the tag service (required)
TAG_URL=http://tag.127.0.0.1.nip.io

These default values work with the standard development setup using 127.0.0.1.nip.io. Adjust them according to your environment.

For detailed information about each environment variable, see the configuration section.

3. Start Development Server​

web-base
npm run dev

The frontend will be available at http://localhost:5173 (default Vite port).

Backend Setup​

1. Configure Docker Environment Variables​

Copy the environment template for Docker services:

dash
cp app/docker/.env.template app/docker/.env

Edit app/docker/.env and set the required passwords:

DEV_PASSWORD=your_password_here
DEV_PASSWORD_URL_ENCODED=your_url_encoded_password_here
warning

You must specify both DEV_PASSWORD and DEV_PASSWORD_URL_ENCODED for the application to function properly. The URL-encoded version is required for database connection strings with special characters.

tip

Optionally, copy the compose override template to customize database port mappings:

cp app/docker/compose.override.sample.yml app/docker/compose.override.yml

2. Start Dependency Services​

Start the required infrastructure and services (Traefik, Keycloak, Tag service, databases):

dash
npm run docker:start

This will start:

  • Traefik - Reverse proxy for service routing
  • IAMs Keycloak - Authentication and authorization service
  • Tag Service - Tag management service
  • PostgreSQL databases - For Keycloak, Tag service, and Dashboard

3. Run Backend Service​

3.1 Setup Backend Environment

Copy the backend environment template:

dash
cp app/.env.template app/.env

3.2 Configure Required Variables

Edit app/.env and set the following:

DEV_PASSWORD=your_password_here
DEV_PASSWORD_URL_ENCODED=your_url_encoded_password_here
warning

Ensure DEV_PASSWORD and DEV_PASSWORD_URL_ENCODED match the passwords specified in app/docker/.env from Step 1.

3.3 Start the Backend Service

dash/app
go mod tidy
go run cmd/dash/main.go

Using the Dashboard Module​

Once installed and running, you can access the dashboard functionality:

The DASH module adds navigation items to your application:

  • Dashboard Management (/aoh/dash) - Main dashboard management interface
  • Favorite Dashboards (/aoh/dash/favourite) - Quick access to favorited dashboards

Creating Your First Dashboard​

  1. Navigate to Dashboard Management - Visit /aoh/dash in your application
  2. Create New Dashboard - Click "Create Dashboard" and provide:
    • Dashboard name and description
    • Initial layout configuration
    • Optional tags for organization
  3. Add Widgets - Use the widget selector to add components:
    • Position widgets using the grid system
    • Configure widget properties
    • Resize widgets as needed
  4. Save and Test - Save your dashboard and test the functionality

Next Steps​

  • Explore Widget Development: Learn how to create custom widgets in the development guide
  • Configure Advanced Features: Set up advanced dashboard features in the configuration section
  • Deploy to Production: Follow the deployment guide for production setup
  • Review Reference Pages: Check the FAQ and troubleshooting guides in the reference section