Getting Started with the Copera Starter Application

The Copera Starter Application is a reference portal that shows how to build a customer-facing web app powered by your Copera workspace. It uses a Board as its database, so you can manage users and tickets directly in Copera while your portal handles authentication, submission, and display.

Prerequisites

Before you begin, make sure you have the following installed and available:

Requirement	Version / Notes
Node.js	>= 24.0.0
pnpm	10.16.1
MongoDB	Local instance or a cloud cluster (e.g., MongoDB Atlas)
Copera workspace	An active workspace with a Board set up (see Step 2)

Step 1: Clone the Repository

The starter application will be published at github.com/copera-ai. Once available, clone it to your local machine:

git clone https://github.com/copera-ai/starter-application.git
cd starter-application

note

If the repository is not yet public, check back at github.com/copera-ai or contact the Copera team for early access.

Step 2: Configure Your Board in Copera

The starter application reads from and writes to a Copera Board. You need to create a Board with two tables — Users and Tickets — and then copy the relevant IDs into the application's config file.

Create the Board

In your Copera workspace, go to Collaborate in the sidebar and create a new Board. Give it a name such as "Portal Data".

Set Up the Users Table

Your Board will have a default table. Rename it to Users and add the following columns:

Column Name	Field Type	Notes
Name	Text	The user's display name
Identifier	Text	The user's email address (used for sign-in)
Password	Password	Stored securely; used for portal authentication
Role	Select (Dropdown)	Add two options: admin and user

Set Up the Tickets Table

Add a second table to the Board and name it Tickets. Add the following columns:

Column Name	Field Type	Notes
Title	Text	A short summary of the ticket
Details	Paragraph (Text)	Full description of the request
User	Link	Link to the Users table
Status	Select (Dropdown)	Add options such as open, in progress, closed
Request Type	Select (Dropdown)	Add options relevant to your use case

Find Your Board ID, Table IDs, and Column IDs

You need to copy several IDs into the application config. Here is where to find each one:

• Board ID — The Board ID appears in the URL when you have the Board open. It looks like: app.copera.ai/boards/6abc123.... Copy the segment after /boards/.
• Table ID — Open the Board, then click the table name tab at the top. The Table ID is shown in the table settings panel, or you can find it in the URL after navigating into the table.
• Column ID — Click the settings icon (gear or three-dot menu) on any column header. The column settings panel will show the column's ID. Copy this value for each column you need to reference.

tip

Keep a text file open as you copy IDs — you will need one Board ID, two Table IDs, and multiple Column IDs before moving on to the next step.

Edit src/config.ts

Open src/config.ts in the cloned repository and fill in the IDs you collected:

export const config = {
  boardId: 'YOUR_BOARD_ID',
  tables: {
    users: {
      tableId: 'YOUR_USERS_TABLE_ID',
      columns: {
        name: 'YOUR_NAME_COLUMN_ID',
        identifier: 'YOUR_IDENTIFIER_COLUMN_ID',
        password: 'YOUR_PASSWORD_COLUMN_ID',
        role: 'YOUR_ROLE_COLUMN_ID',
      },
    },
    tickets: {
      tableId: 'YOUR_TICKETS_TABLE_ID',
      columns: {
        title: 'YOUR_TITLE_COLUMN_ID',
        details: 'YOUR_DETAILS_COLUMN_ID',
        user: 'YOUR_USER_COLUMN_ID',
        status: 'YOUR_STATUS_COLUMN_ID',
        requestType: 'YOUR_REQUEST_TYPE_COLUMN_ID',
      },
    },
  },
};

Step 3: Set Up Environment Variables

The application uses a .env file to store secrets and connection details. Copy the example file to get started:

cp .env.example .env

Open .env and fill in the following values:

Variable	Description
MONGODB_URI	The connection string for your MongoDB instance (e.g., mongodb://localhost:27017/starter or your Atlas URI)
APP_TOKEN	Any secret string used to sign JWTs for the portal's session management (e.g., a long random string)
COPERA_API_KEY	Your workspace API key, found in Workspace Settings > API in Copera

For the web (frontend) app, set one additional variable:

Variable	Description
VITE_SERVER_URL	The URL where the API server will run (e.g., http://localhost:3000)

tip

You can generate a secure random string for APP_TOKEN using openssl rand -hex 32 in your terminal.

Finding Your Copera API Key

1. In Copera, click your workspace name in the top-left corner.
2. Go to Settings > API.
3. Generate or copy your API key.

Step 4: Install Dependencies and Run

With configuration complete, install dependencies and start both the API and web app together:

pnpm install
pnpm dev

This starts both services concurrently:

• API server — runs on the port defined in your .env (default: http://localhost:3000)
• Web app — runs on the Vite dev server (default: http://localhost:5173)

Open your browser and navigate to the web app URL. You will see the portal sign-in page.

Step 5: Create Your First User

The portal does not have a public registration form by default — users are managed directly in your Copera Board. To create the first user:

1. In Copera, open the Board you configured and navigate to the Users table.
2. Add a new row and fill in the Name, Identifier (email), Password, and Role columns.
3. Return to the web app in your browser.
4. Sign in using the email and password you just entered.

note

Passwords entered in the Board are handled by the application's authentication layer. The exact behavior depends on how the starter app processes credentials — refer to the src/config.ts and auth service files for details.

What's Next

Now that the application is running, here are some directions to take it further:

• Customize the portal for your use case — Adjust the UI, add new pages, or change the ticket form fields to match your workflow.
• Add columns to your Board — Any new column you add in Copera can be referenced in the app by adding its Column ID to src/config.ts.
• Use AI tools to build new features — The starter app is designed to be a starting point. Use AI coding assistants alongside the Copera API to accelerate development.
• Explore the Copera API — Review the API reference to understand what data operations are available beyond what the starter app demonstrates.

tip

When you add a new column to your Board in Copera, remember to also add its Column ID to the relevant section of src/config.ts so the application can read and write that field.