Erste Schritte mit der Copera Starter Application

Die Copera Starter Application ist ein Referenzportal, das zeigt, wie Sie eine kundenorientierte Web-App auf Basis Ihres Copera-Workspace bauen. Sie nutzt ein Board als Datenbank, sodass Sie Benutzer und Tickets direkt in Copera verwalten, während das Portal Authentifizierung, Einreichung und Anzeige übernimmt.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Folgendes installiert und verfügbar ist:

Anforderung	Version / Hinweise
Node.js	>= 24.0.0
pnpm	11.9.0
Datenbank	Eine lokale Instanz oder eine verwaltete Cloud-Datenbank
Copera-Workspace	Ein aktiver Workspace mit eingerichtetem Board (siehe Schritt 2)

Schritt 1: Repository klonen

Die Starter Application wird unter github.com/copera-ai veröffentlicht. Sobald verfügbar, klonen Sie sie lokal:

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

hinweis

Wenn das Repository noch nicht öffentlich ist, schauen Sie unter github.com/copera-ai nach oder kontaktieren Sie das Copera-Team für Early Access.

Schritt 2: Board in Copera konfigurieren

Die Starter Application liest von und schreibt in ein Copera Board. Sie müssen ein Board mit zwei Tabellen anlegen — Users und Tickets — und die relevanten IDs in die Config-Datei der Anwendung kopieren.

Board anlegen

Gehen Sie in Ihrem Copera-Workspace zu Collaborate in der Sidebar und erstellen Sie ein neues Board. Geben Sie ihm einen Namen wie „Portal Data“.

Users-Tabelle einrichten

Ihr Board hat eine Standard-Tabelle. Benennen Sie sie in Users um und fügen Sie folgende Spalten hinzu:

Spaltenname	Feldtyp	Hinweise
Name	Text	Anzeigename des Benutzers
Identifier	Text	E-Mail-Adresse des Benutzers (für Sign-in)
Password	Password	Sicher gespeichert; für Portal-Authentifizierung
Role	Select (Dropdown)	Zwei Optionen hinzufügen: admin und user

Tickets-Tabelle einrichten

Fügen Sie eine zweite Tabelle zum Board hinzu und nennen Sie sie Tickets. Fügen Sie folgende Spalten hinzu:

Spaltenname	Feldtyp	Hinweise
Title	Text	Kurze Zusammenfassung des Tickets
Details	Paragraph (Text)	Vollständige Beschreibung der Anfrage
User	Link	Link zur Users-Tabelle
Status	Select (Dropdown)	Optionen wie open, in progress, closed
Request Type	Select (Dropdown)	Optionen passend zu Ihrem Use Case

Board-ID, Tabellen-IDs und Spalten-IDs finden

Sie müssen mehrere IDs in die App-Config kopieren. So finden Sie jede:

• Board-ID — erscheint in der URL, wenn das Board geöffnet ist. Sie sieht aus wie: app.copera.ai/boards/6abc123.... Kopieren Sie das Segment nach /boards/.
• Tabellen-ID — Board öffnen, dann den Tabellenname-Tab oben anklicken. Die Tabellen-ID steht im Tabellen-Einstellungspanel oder in der URL nach dem Navigieren in die Tabelle.
• Spalten-ID — Klicken Sie das Einstellungen-Icon (Zahnrad oder Drei-Punkte-Menü) am Spaltenkopf. Das Spalten-Einstellungspanel zeigt die Spalten-ID. Kopieren Sie den Wert für jede benötigte Spalte.

Für eine vollständige Anleitung siehe Board-, Tabellen- und Spalten-IDs finden.

tipp

Halten Sie eine Textdatei offen, während Sie IDs kopieren — Sie brauchen eine Board-ID, zwei Tabellen-IDs und mehrere Spalten-IDs, bevor Sie zum nächsten Schritt gehen.

src/config.ts bearbeiten

Öffnen Sie src/config.ts im geklonten Repository und tragen Sie die gesammelten IDs ein:

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

Schritt 3: Umgebungsvariablen setzen

Die Anwendung nutzt eine .env-Datei für Secrets und Verbindungsdaten. Kopieren Sie die Beispieldatei zum Start:

cp .env.example .env

Öffnen Sie .env und füllen Sie folgende Werte aus:

Variable	Beschreibung
MONGODB_URI	Connection-String Ihrer Datenbankinstanz (z. B. mongodb://localhost:27017/starter oder Ihre Atlas-URI)
APP_TOKEN	Beliebiger Secret-String zum Signieren von JWTs für das Session-Management des Portals (z. B. ein langer Zufallsstring)
COPERA_API_KEY	Ein Copera-API-Token für das SDK. Integration API Key (Präfix cp_key_) oder Personal Access Token (Präfix cp_pat_), erstellt unter Workspace-Einstellungen → Integrationen

Für die Web-(Frontend-)App setzen Sie eine weitere Variable:

Variable	Beschreibung
VITE_SERVER_URL	URL, unter der der API-Server läuft (z. B. http://localhost:3000)

tipp

Einen sicheren Zufallsstring für APP_TOKEN erzeugen Sie mit openssl rand -hex 32 im Terminal.

Ihr Copera-API-Token finden

1. In Copera Workspace-Einstellungen → Integrationen öffnen.
2. Für einen Integration API Key (Präfix cp_key_) den Tab API Keys öffnen und einen neuen Key erstellen. Integration API Keys decken Board- und Channel-Operationen ab — alles, was die Starter Application braucht.
3. Für ein Personal Access Token (Präfix cp_pat_) den Tab Personal Tokens öffnen und ein neues Token erstellen. Ein PAT schaltet die volle API-Oberfläche frei.
4. Token sofort kopieren — es wird nur einmal angezeigt — und in COPERA_API_KEY in Ihrer .env einfügen.

Für eine tiefere Erklärung der Token-Typen und Scopes siehe den Authentifizierungs-Leitfaden.

Schritt 4: Dependencies installieren und starten

Mit abgeschlossener Konfiguration Dependencies installieren und API sowie Web-App zusammen starten:

pnpm install
pnpm dev

Das startet beide Services parallel:

• API-Server — Port aus Ihrer .env (Standard: http://localhost:3000)
• Web-App — Dev-Server (Standard: http://localhost:5173)

Öffnen Sie den Browser und navigieren Sie zur Web-App-URL. Sie sehen die Portal-Sign-in-Seite.

Schritt 5: Ersten Benutzer anlegen

Das Portal hat standardmäßig kein öffentliches Registrierungsformular — Benutzer werden direkt in Ihrem Copera Board verwaltet. So legen Sie den ersten Benutzer an:

1. In Copera das konfigurierte Board öffnen und zur Users-Tabelle navigieren.
2. Eine neue Zeile anlegen und die Spalten Name, Identifier (E-Mail), Password und Role ausfüllen.
3. Zurück zur Web-App im Browser.
4. Mit der soeben eingegebenen E-Mail und dem Passwort anmelden.

hinweis

Im Board eingegebene Passwörter werden von der Auth-Schicht der Anwendung verarbeitet. Das genaue Verhalten hängt davon ab, wie die Starter App Credentials verarbeitet — Details in src/config.ts und den Auth-Service-Dateien.

Was als Nächstes

Sobald die Anwendung läuft, können Sie sie weiterführen:

• Portal für Ihren Use Case anpassen — UI anpassen, neue Seiten hinzufügen oder Ticket-Formularfelder an Ihren Workflow anpassen.
• Spalten zum Board hinzufügen — Jede neue Spalte in Copera kann in der App referenziert werden, indem Sie ihre Spalten-ID in src/config.ts eintragen.
• KI-Tools für neue Features nutzen — Die Starter App ist als Ausgangspunkt gedacht. Nutzen Sie KI-Coding-Assistenten zusammen mit der Copera API, um die Entwicklung zu beschleunigen.
• Copera API erkunden — Die API-Referenz zeigt, welche Datenoperationen über das hinaus möglich sind, was die Starter App demonstriert.

tipp

Wenn Sie in Copera eine neue Spalte zum Board hinzufügen, tragen Sie ihre Spalten-ID auch im passenden Abschnitt von src/config.ts ein, damit die Anwendung das Feld lesen und schreiben kann.