Premiers pas avec la Copera Starter Application

La Copera Starter Application est un portail de référence qui montre comment construire une app web orientée client alimentée par votre workspace Copera. Elle utilise un Board comme base de données, afin que vous puissiez gérer les utilisateurs et les tickets directement dans Copera tandis que votre portail gère l'authentification, la soumission et l'affichage.

Prérequis

Avant de commencer, assurez-vous d'avoir installé et disponible :

Exigence	Version / Notes
Node.js	>= 24.0.0
pnpm	11.9.0
Base de données	Une instance locale ou une base de données cloud managée
Workspace Copera	Un workspace actif avec un Board configuré (voir Étape 2)

Étape 1 : Cloner le dépôt

La starter application sera publiée sur github.com/copera-ai. Une fois disponible, clonez-la sur votre machine locale :

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

note

Si le dépôt n'est pas encore public, revenez sur github.com/copera-ai ou contactez l'équipe Copera pour un accès anticipé.

Étape 2 : Configurer votre Board dans Copera

La starter application lit et écrit dans un Board Copera. Vous devez créer un Board avec deux tables — Users et Tickets — puis copier les IDs pertinents dans le fichier de configuration de l'application.

Créer le Board

Dans votre workspace Copera, allez dans Collaborate dans la barre latérale et créez un nouveau Board. Donnez-lui un nom comme « Portal Data ».

Configurer la table Users

Votre Board aura une table par défaut. Renommez-la en Users et ajoutez les colonnes suivantes :

Nom de colonne	Type de champ	Notes
Name	Text	Le nom d'affichage de l'utilisateur
Identifier	Text	L'adresse e-mail de l'utilisateur (utilisée pour la connexion)
Password	Password	Stocké de façon sécurisée ; utilisé pour l'authentification du portail
Role	Select (Dropdown)	Ajoutez deux options : admin et user

Configurer la table Tickets

Ajoutez une seconde table au Board et nommez-la Tickets. Ajoutez les colonnes suivantes :

Nom de colonne	Type de champ	Notes
Title	Text	Un court résumé du ticket
Details	Paragraph (Text)	Description complète de la demande
User	Link	Lien vers la table Users
Status	Select (Dropdown)	Ajoutez des options comme open, in progress, closed
Request Type	Select (Dropdown)	Ajoutez des options pertinentes pour votre cas d'usage

Trouver votre Board ID, Table IDs et Column IDs

Vous devez copier plusieurs IDs dans la configuration de l'application. Voici où trouver chacun :

• Board ID — Le Board ID apparaît dans l'URL lorsque le Board est ouvert. Il ressemble à : app.copera.ai/boards/6abc123.... Copiez le segment après /boards/.
• Table ID — Ouvrez le Board, puis cliquez sur l'onglet du nom de table en haut. Le Table ID est affiché dans le panneau de paramètres de la table, ou vous pouvez le trouver dans l'URL après être entré dans la table.
• Column ID — Cliquez sur l'icône de paramètres (engrenage ou menu à trois points) sur n'importe quel en-tête de colonne. Le panneau de paramètres de colonne affichera l'ID de la colonne. Copiez cette valeur pour chaque colonne que vous devez référencer.

Pour un parcours complet, voir Trouver les Board, Table et Column IDs.

astuce

Gardez un fichier texte ouvert pendant que vous copiez les IDs — vous aurez besoin d'un Board ID, de deux Table IDs, et de plusieurs Column IDs avant de passer à l'étape suivante.

Éditer src/config.ts

Ouvrez src/config.ts dans le dépôt cloné et renseignez les IDs que vous avez collectés :

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

Étape 3 : Configurer les variables d'environnement

L'application utilise un fichier .env pour stocker les secrets et les détails de connexion. Copiez le fichier d'exemple pour commencer :

cp .env.example .env

Ouvrez .env et renseignez les valeurs suivantes :

Variable	Description
MONGODB_URI	La chaîne de connexion de votre instance de base de données (p. ex. mongodb://localhost:27017/starter ou votre URI Atlas)
APP_TOKEN	Toute chaîne secrète utilisée pour signer les JWT pour la gestion de session du portail (p. ex. une longue chaîne aléatoire)
COPERA_API_KEY	Un token d'API Copera utilisé par le SDK. Utilisez une Integration API Key (préfixe cp_key_) ou un Personal Access Token (préfixe cp_pat_), créés dans Workspace Settings → Integrations

Pour l'app web (frontend), définissez une variable supplémentaire :

Variable	Description
VITE_SERVER_URL	L'URL où le serveur API s'exécutera (p. ex. http://localhost:3000)

astuce

Vous pouvez générer une chaîne aléatoire sécurisée pour APP_TOKEN avec openssl rand -hex 32 dans votre terminal.

Trouver votre token d'API Copera

1. Dans Copera, ouvrez Workspace Settings → Integrations.
2. Pour créer une Integration API Key (préfixe cp_key_), ouvrez l'onglet API Keys et créez une nouvelle clé. Les Integration API Keys fonctionnent pour les opérations board et channel, ce dont a besoin la Starter Application.
3. Pour créer un Personal Access Token à la place (préfixe cp_pat_), ouvrez l'onglet Personal Tokens et créez un nouveau token. Un PAT débloque la surface API complète.
4. Copiez le token immédiatement — il n'est affiché qu'une seule fois — et collez-le dans COPERA_API_KEY dans votre fichier .env.

Pour une explication plus approfondie des types de tokens et des scopes, voir le guide d'authentification.

Étape 4 : Installer les dépendances et lancer

Avec la configuration terminée, installez les dépendances et démarrez l'API et l'app web ensemble :

pnpm install
pnpm dev

Cela démarre les deux services en concurrent :

• Serveur API — s'exécute sur le port défini dans votre .env (défaut : http://localhost:3000)
• App web — s'exécute sur le serveur de dev (défaut : http://localhost:5173)

Ouvrez votre navigateur et naviguez vers l'URL de l'app web. Vous verrez la page de connexion du portail.

Étape 5 : Créer votre premier utilisateur

Le portail n'a pas de formulaire d'inscription public par défaut — les utilisateurs sont gérés directement dans votre Board Copera. Pour créer le premier utilisateur :

1. Dans Copera, ouvrez le Board que vous avez configuré et naviguez vers la table Users.
2. Ajoutez une nouvelle ligne et renseignez les colonnes Name, Identifier (e-mail), Password et Role.
3. Revenez à l'app web dans votre navigateur.
4. Connectez-vous avec l'e-mail et le mot de passe que vous venez de saisir.

note

Les mots de passe saisis dans le Board sont gérés par la couche d'authentification de l'application. Le comportement exact dépend de la façon dont la starter app traite les identifiants — consultez src/config.ts et les fichiers du service d'auth pour les détails.

Et ensuite

Maintenant que l'application tourne, voici quelques directions pour aller plus loin :

• Personnaliser le portail pour votre cas d'usage — Ajustez l'UI, ajoutez de nouvelles pages, ou changez les champs du formulaire de ticket pour correspondre à votre workflow.
• Ajouter des colonnes à votre Board — Toute nouvelle colonne que vous ajoutez dans Copera peut être référencée dans l'app en ajoutant son Column ID à src/config.ts.
• Utiliser des outils IA pour construire de nouvelles fonctionnalités — La starter app est conçue comme un point de départ. Utilisez des assistants de code IA aux côtés de l'API Copera pour accélérer le développement.
• Explorer l'API Copera — Consultez la Référence de l'API pour comprendre quelles opérations de données sont disponibles au-delà de ce que la starter app démontre.

astuce

Lorsque vous ajoutez une nouvelle colonne à votre Board dans Copera, n'oubliez pas d'ajouter aussi son Column ID à la section pertinente de src/config.ts pour que l'application puisse lire et écrire ce champ.