Primi passi con la Copera Starter Application

La Copera Starter Application è un portal di riferimento che mostra come costruire una web app rivolta ai clienti alimentata dal workspace Copera. Usa una Board come database, così puoi gestire utenti e ticket direttamente in Copera mentre il portal gestisce autenticazione, invio e visualizzazione.

Prerequisiti

Prima di iniziare, assicurati di avere installato e disponibile quanto segue:

Requirement	Version / Notes
Node.js	>= 24.0.0
pnpm	11.9.0
Database	A local instance or a managed cloud database
Copera workspace	An active workspace with a Board set up (see Step 2)

Passo 1: Clona il repository

La starter application sarà pubblicata su github.com/copera-ai. Quando disponibile, clonaldela sulla macchina locale:

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

nota

Se il repository non è ancora pubblico, controlla di nuovo su github.com/copera-ai o contatta il team Copera per early access.

Passo 2: Configura la Board in Copera

La starter application legge da e scrive su una Copera Board. Devi creare una Board con due table — Users e Tickets — e poi copiare gli ID rilevanti nel file di config dell'applicazione.

Crea la Board

Nel workspace Copera, vai su Collaborate nella sidebar e crea una nuova Board. Dalle un nome come "Portal Data".

Imposta la table Users

La Board avrà una table di default. Rinominala in Users e aggiungi le seguenti colonne:

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

Imposta la table Tickets

Aggiungi una seconda table alla Board e chiamala Tickets. Aggiungi le seguenti colonne:

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

Trova Board ID, Table ID e Column ID

Devi copiare diversi ID nella config dell'applicazione. Ecco dove trovare ciascuno:

• Board ID — Il Board ID compare nell'URL quando hai la Board aperta. Sembra: app.copera.ai/boards/6abc123.... Copia il segmento dopo /boards/.
• Table ID — Apri la Board, poi clicca la tab del nome table in alto. Il Table ID è mostrato nel pannello table settings, oppure lo trovi nell'URL dopo essere entrato nella table.
• Column ID — Clicca l'icona settings (ingranaggio o menu a tre puntini) su qualsiasi header di colonna. Il pannello column settings mostra l'ID della colonna. Copia questo valore per ogni colonna che devi referenziare.

Per una walkthrough completa, vedi Trovare Board, Table e Column ID.

suggerimento

Tieni aperto un file di testo mentre copi gli ID — ti serviranno un Board ID, due Table ID e più Column ID prima di passare al passo successivo.

Modifica src/config.ts

Apri src/config.ts nel repository clonato e compila gli ID che hai raccolto:

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',
      },
    },
  },
};

Passo 3: Imposta le variabili d'ambiente

L'applicazione usa un file .env per memorizzare secret e dettagli di connessione. Copia il file di esempio per iniziare:

cp .env.example .env

Apri .env e compila i seguenti valori:

Variable	Description
MONGODB_URI	The connection string for your database 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	A Copera API token used by the SDK. Use an Integration API Key (prefixed cp_key_) or a Personal Access Token (prefixed cp_pat_), created in Workspace Settings → Integrations

Per l'app web (frontend), imposta una variabile aggiuntiva:

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

suggerimento

Puoi generare una stringa random sicura per APP_TOKEN usando openssl rand -hex 32 nel terminale.

Trovare il token API Copera

1. In Copera, apri Workspace Settings → Integrations.
2. Per creare un'Integration API Key (prefisso cp_key_), apri la tab API Keys e crea una nuova key. Le Integration API Key funzionano per le operazioni board e channel, che è tutto ciò di cui ha bisogno la Starter Application.
3. Per creare invece un Personal Access Token (prefisso cp_pat_), apri la tab Personal Tokens e crea un nuovo token. Un PAT sblocca l'intera superficie API.
4. Copia il token immediatamente — viene mostrato una sola volta — e incollalo in COPERA_API_KEY nel file .env.

Per una spiegazione più approfondita di tipi di token e scope, vedi la guida Autenticazione.

Passo 4: Installa le dipendenze ed esegui

Con la configurazione completa, installa le dipendenze e avvia insieme API e web app:

pnpm install
pnpm dev

Questo avvia entrambi i servizi in concurrent:

• API server — gira sulla porta definita nel .env (default: http://localhost:3000)
• Web app — gira sul dev server (default: http://localhost:5173)

Apri il browser e naviga all'URL della web app. Vedrai la pagina di sign-in del portal.

Passo 5: Crea il primo utente

Il portal non ha un form di registrazione pubblico di default — gli utenti si gestiscono direttamente nella Copera Board. Per creare il primo utente:

1. In Copera, apri la Board che hai configurato e naviga alla table Users.
2. Aggiungi una nuova riga e compila le colonne Name, Identifier (email), Password e Role.
3. Torna alla web app nel browser.
4. Accedi usando l'email e la password che hai appena inserito.

nota

Le password inserite nella Board sono gestite dal layer di autenticazione dell'applicazione. Il comportamento esatto dipende da come la starter app elabora le credenziali — fai riferimento a src/config.ts e ai file del servizio auth per i dettagli.

Cosa fare dopo

Ora che l'applicazione è in esecuzione, ecco alcune direzioni per portarla avanti:

• Personalizza il portal per il tuo caso d'uso — Aggiusta la UI, aggiungi nuove pagine o cambia i field del form ticket per allinearti al workflow.
• Aggiungi colonne alla Board — Qualsiasi nuova colonna che aggiungi in Copera può essere referenziata nell'app aggiungendo il suo Column ID a src/config.ts.
• Usa tool IA per costruire nuove feature — La starter app è pensata come punto di partenza. Usa assistenti di coding con IA insieme all'API Copera per accelerare lo sviluppo.
• Esplora l'API Copera — Rivedi l'API Reference per capire quali operazioni sui dati sono disponibili oltre a ciò che la starter app dimostra.

suggerimento

Quando aggiungi una nuova colonna alla Board in Copera, ricorda di aggiungere anche il suo Column ID alla sezione rilevante di src/config.ts così l'applicazione può leggere e scrivere quel field.