⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
docs: reorganize documentation into core folder
Andrej Acevskieb5b0bd3d8dc
diff --git a/apps/docs/content/docs/core/guide/meta.json b/apps/docs/content/docs/core/guide/meta.jsonnew file mode 100644index 000000000..c9dc98691--- /dev/null+++ b/apps/docs/content/docs/core/guide/meta.json@@ -0,0 +1,6 @@+{+ "title": "Guide",+ "icon": "Book",+ "pages": ["index", "migrating-from-v1"],+ "defaultOpen": true+}diff --git a/apps/docs/content/docs/core/guide/migrating-from-v1.mdx b/apps/docs/content/docs/core/guide/migrating-from-v1.mdxnew file mode 100644index 000000000..b8bb16359--- /dev/null+++ b/apps/docs/content/docs/core/guide/migrating-from-v1.mdx@@ -0,0 +1,59 @@+---+title: Migrating from v1+description: This guide will help you migrate your Kaneo instance from v1 to v2.+---++## Overview++Migrating from v1 to v2 is a straightforward process. We have updated the environment variables and the compose file to use the new variables.++> **Note:** Please backup your database before migrating.++## Environment variables++The environment variables are used to configure the application.++The big change is that we are using a `.env` file to store the variables.++1. Create a `.env` file in the root of the project.+2. JWT_ACCESS has been changed to AUTH_SECRET.++Other than that, there's newly introduced environment variables that you need to set.+++- `KANEO_CLIENT_URL` (required)+- `AUTH_SECRET` (required)+- `DATABASE_URL` (required)+- `POSTGRES_DB` (required)+- `POSTGRES_USER` (required)+- `POSTGRES_PASSWORD` (required)+- `CORS_ORIGINS` (optional)+- `SMTP_HOST` (optional)+- `SMTP_PORT` (optional)+- `SMTP_SECURE` (optional)+- `SMTP_USER` (optional)+- `SMTP_PASSWORD` (optional)+- `SMTP_FROM` (optional)++For more information, see the [Environment variables](/docs/installation/environment-variables) page.++## Compose file++The compose file has been updated to use the new environment variables.++```yml+services:+ api:+ image: ghcr.io/usekaneo/api:latest+ env_file:+ - .env+ ...++ web:+ image: ghcr.io/usekaneo/web:latest+ env_file:+ - .env+ ...+```++For the complete compose file, see the [Docker Compose](/docs/installation/docker-compose) page.\ No newline at end of filediff --git a/apps/docs/content/docs/core/index.mdx b/apps/docs/content/docs/core/index.mdxnew file mode 100644index 000000000..3b0e5c0fb--- /dev/null+++ b/apps/docs/content/docs/core/index.mdx@@ -0,0 +1,27 @@+---+title: Quick Start+description: Get started with Kaneo in minutes+icon: Album+---++## Introduction++Kaneo <span className='text-fd-muted-foreground text-sm'>(/kəˈneɪ.oʊ/)</span> is a project management tool that gets out of your way. It is designed to be a simple, yet powerful tool for managing your projects. It **works for you** instead of you working for it.++### Components++Kaneo is composed of several components:++- API: The backend API that powers the application, it is built with Hono and TypeScript.+- Web: The frontend web application that is built with React and Tailwind CSS.+- Database: The database that is built with PostgreSQL.++### Installation++The installation process is straightforward, we have a Docker Compose file that will start the required services.++It is part of a three part installation process.++- [Setting up the Docker compose file](/docs/installation/docker-compose)+- [Setting up the environment variables](/docs/installation/environment-variables)+- [Starting the services](/docs/installation/start-services)diff --git a/apps/docs/content/docs/core/installation/docker-compose.mdx b/apps/docs/content/docs/core/installation/docker-compose.mdxnew file mode 100644index 000000000..6537cfc88--- /dev/null+++ b/apps/docs/content/docs/core/installation/docker-compose.mdx@@ -0,0 +1,54 @@+---+title: The compose.yml file+description: The Docker Compose file is used to start the required services.+---++## The initial compose file++The first step is to create a Docker Compose file. We will call it `compose.yml`.++```yml+services:+ postgres:+ image: postgres:16-alpine+ env_file:+ - .env+ ports:+ - "5432:5432"+ volumes:+ - postgres_data:/var/lib/postgresql/data+ restart: unless-stopped++ api:+ image: ghcr.io/usekaneo/api:latest+ ports:+ - "1337:1337"+ env_file:+ - .env+ restart: unless-stopped++ web:+ image: ghcr.io/usekaneo/web:latest+ ports:+ - "5173:5173"+ env_file:+ - .env+ restart: unless-stopped++volumes:+ postgres_data:+```++## The services and volumes++Kaneo utilities the following services:++- `postgres`: The PostgreSQL database.+- `api`: The API server.+- `web`: The web application.++Additionally, the following volumes are used:++- `postgres_data`: The PostgreSQL data.++After creating the compose file, the next step is to set up the environment variables.\ No newline at end of filediff --git a/apps/docs/content/docs/core/installation/environment-variables.mdx b/apps/docs/content/docs/core/installation/environment-variables.mdxnew file mode 100644index 000000000..c63e4a223--- /dev/null+++ b/apps/docs/content/docs/core/installation/environment-variables.mdx@@ -0,0 +1,101 @@+---+title: Environment variables+description: The environment variables are used to configure the application.+---++## Set up the file++The environment variables are used to configure the application. We will use a `.env` file to store the variables.++The variables are split up into the following sections:++- [General URLs](#general-urls)+- [Database](#database)+- [Authentication](#authentication)+- [GitHub SSO & Integration](#github-sso-&-integration)+- [Google SSO](#google-sso)+- [Custom OAuth/OIDC](#custom-oauth-oidc)+- [SMTP Configuration](#smtp-configuration)++## Required variables++### General URLs++This section will cover all the variables related to the general URLs.++Name | Description |+--- | --- |+| `KANEO_CLIENT_URL` | The URL of the web application.+| `KANEO_API_URL` | The URL of the API.++### Database++This section will cover all the variables related to the database.++Name | Description |+--- | --- |+| `DATABASE_URL` | The URL of the PostgreSQL database.+| `POSTGRES_DB` | The name of the PostgreSQL database.+| `POSTGRES_USER` | The username for the PostgreSQL database.+| `POSTGRES_PASSWORD` | The password for the PostgreSQL database.++### Authentication++This section will cover all the variables related to the authentication.++Name | Description |+--- | --- |+| `AUTH_SECRET` | The secret key for the JWT token.+++## Optional variables++### GitHub SSO & Integration++Name | Description |+--- | --- |+| `GITHUB_CLIENT_ID` | The GitHub client ID.+| `GITHUB_CLIENT_SECRET` | The GitHub client secret.+| `GITHUB_APP_ID` | The GitHub app ID.+| `GITHUB_WEBHOOK_SECRET` | The GitHub webhook secret.+| `GITHUB_PRIVATE_KEY` | The GitHub private key.++### Google SSO++Name | Description |+--- | --- |+| `GOOGLE_CLIENT_ID` | The Google client ID.+| `GOOGLE_CLIENT_SECRET` | The Google client secret.++### Custom OAuth/OIDC++Name | Description |+--- | --- |+| `CUSTOM_OAUTH_CLIENT_ID` | OAuth client ID from your provider.+| `CUSTOM_OAUTH_CLIENT_SECRET` | OAuth client secret from your provider.+| `CUSTOM_OAUTH_AUTHORIZATION_URL` | Authorization endpoint URL.+| `CUSTOM_OAUTH_TOKEN_URL` | Token exchange endpoint URL.+| `CUSTOM_OAUTH_USER_INFO_URL` | User info endpoint URL.+| `CUSTOM_OAUTH_DISCOVERY_URL` | (Optional) OpenID Connect discovery document URL.+| `CUSTOM_OAUTH_SCOPES` | (Optional) Comma-separated list of OAuth scopes. Default: `profile,email`.+| `CUSTOM_OAUTH_RESPONSE_TYPE` | (Optional) OAuth response type. Default: `code`.+| `CUSTOM_AUTH_PKCE` | (Optional) Enable/disable PKCE. Default: `true`.++### SMTP Configuration++Name | Description |+--- | --- |+| `SMTP_HOST` | The SMTP host.+| `SMTP_PORT` | The SMTP port.+| `SMTP_SECURE` | Whether to use SSL/TLS.+| `SMTP_USER` | The SMTP user.+| `SMTP_PASSWORD` | The SMTP password.+| `SMTP_FROM` | The SMTP from address.+| `SMTP_REQUIRE_TLS` | Whether to explicitly force to use TLS. [See more on](https://nodemailer.com/smtp#tls-options).++## Key points++- If you enable GitHub SSO, you need to set up the GitHub app which is used to authenticate users in the [GitHub Developer Settings](https://github.com/settings/developers). See the [GitHub SSO guide](/docs/social-providers/github).+- If you enable Google SSO, you need to set up the Google app which is used to authenticate users in the [Google Cloud Console](https://console.cloud.google.com/). See the [Google SSO guide](/docs/social-providers/google).+- If you enable Custom OAuth/OIDC, you need to configure your identity provider with the appropriate redirect URI. See the [Custom OAuth/OIDC guide](/docs/social-providers/custom-oauth).+- If you have enabled SMTP, your sign in will be done via email using a magic link.diff --git a/apps/docs/content/docs/core/installation/meta.json b/apps/docs/content/docs/core/installation/meta.jsonnew file mode 100644index 000000000..ac7f72440--- /dev/null+++ b/apps/docs/content/docs/core/installation/meta.json@@ -0,0 +1,11 @@+{+ "title": "Installation",+ "icon": "Package",+ "pages": [+ "index",+ "docker-compose",+ "environment-variables",+ "start-services"+ ],+ "defaultOpen": true+}diff --git a/apps/docs/content/docs/core/installation/start-services.mdx b/apps/docs/content/docs/core/installation/start-services.mdxnew file mode 100644index 000000000..a0b031a07--- /dev/null+++ b/apps/docs/content/docs/core/installation/start-services.mdx@@ -0,0 +1,21 @@+---+title: Start the services+description: Start the services to start using Kaneo+---++## Start the services++Congratulations! You have now set up the services to start using Kaneo.++To start the services, you can use the following command:++```bash+docker compose up -d+```++You can now access the web application at [http://localhost:5173](http://localhost:5173).++The next logical step would be to set up a reverse proxy to access the web application from the internet.++- Nginx+- Traefikdiff --git a/apps/docs/content/docs/core/integrations/github/configuration.mdx b/apps/docs/content/docs/core/integrations/github/configuration.mdxnew file mode 100644index 000000000..5ae8671c9--- /dev/null+++ b/apps/docs/content/docs/core/integrations/github/configuration.mdx@@ -0,0 +1,228 @@+---+title: Configuration & Setup+description: Configure Kaneo with your GitHub App credentials and connect projects to repositories. Includes Docker Compose and Kubernetes examples.+---++import { Step, Steps } from 'fumadocs-ui/components/steps';+import { Callout } from 'fumadocs-ui/components/callout';++This guide covers configuring Kaneo with your GitHub App credentials and connecting projects to repositories.++<Callout type="info">+Make sure you've completed the [GitHub App setup](/docs/integrations/github/setup) before proceeding.+</Callout>++## Environment Variables++Add the following environment variables to your Kaneo deployment:++```bash+# GitHub App Configuration+GITHUB_APP_ID=123456+GITHUB_CLIENT_ID=Iv1.abc123def456+GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu+GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----+MIIEpAIBAAKCAQEA...+[Full contents of your private key]+...+-----END RSA PRIVATE KEY-----"+GITHUB_WEBHOOK_SECRET=your-webhook-secret-here++# Optional: GitHub App Name for installation URLs+GITHUB_APP_NAME=kaneo-your-instance-name+```++### Variable Reference++| Variable | Description | Required | Example |+|----------|-------------|----------|---------|+| `GITHUB_APP_ID` | Your GitHub App's ID | ✅ | `123456` |+| `GITHUB_CLIENT_ID` | OAuth client ID from your app | ✅ | `Iv1.abc123def456` |+| `GITHUB_CLIENT_SECRET` | OAuth client secret | ✅ | `abc123def456ghi789jkl012mno345pqr678stu` |+| `GITHUB_PRIVATE_KEY` | Full private key content (with newlines) | ✅ | `-----BEGIN RSA...` |+| `GITHUB_WEBHOOK_SECRET` | Secret for webhook verification | ✅ | `your-secret` |+| `GITHUB_APP_NAME` | App name for installation URLs | ⚠️ | `kaneo-mycompany` |++<Callout type="warning">+`GITHUB_APP_NAME` is optional but recommended. It's used to generate direct installation links in the UI.+</Callout>++## Deployment Examples++### Docker Compose++Update your `compose.yml` file:++```yaml+services:+ backend:+ image: ghcr.io/usekaneo/api:latest+ environment:+ # ... other environment variables+ GITHUB_APP_ID: "123456"+ GITHUB_CLIENT_ID: "Iv1.abc123def456"+ GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"+ GITHUB_PRIVATE_KEY: |+ -----BEGIN RSA PRIVATE KEY-----+ MIIEpAIBAAKCAQEA...+ [Full contents of your private key]+ ...+ -----END RSA PRIVATE KEY-----+ GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"+ GITHUB_APP_NAME: "kaneo-mycompany"+ # ... rest of configuration+```++<Callout type="tip">+Use the `|` YAML syntax for multi-line environment variables like the private key.+</Callout>++### Kubernetes++Create a secret for your GitHub credentials:++```yaml+apiVersion: v1+kind: Secret+metadata:+ name: github-integration+ namespace: kaneo+type: Opaque+stringData:+ GITHUB_APP_ID: "123456"+ GITHUB_CLIENT_ID: "Iv1.abc123def456"+ GITHUB_CLIENT_SECRET: "abc123def456ghi789jkl012mno345pqr678stu"+ GITHUB_PRIVATE_KEY: |+ -----BEGIN RSA PRIVATE KEY-----+ MIIEpAIBAAKCAQEA...+ [Full contents of your private key]+ ...+ -----END RSA PRIVATE KEY-----+ GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"+ GITHUB_APP_NAME: "kaneo-mycompany"+```++Then reference it in your deployment:++```yaml+apiVersion: apps/v1+kind: Deployment+metadata:+ name: kaneo-backend+spec:+ template:+ spec:+ containers:+ - name: backend+ image: ghcr.io/usekaneo/api:latest+ envFrom:+ - secretRef:+ name: github-integration+```++### Environment File++For development or simple deployments, create a `.env` file:++```bash+# .env file+GITHUB_APP_ID=123456+GITHUB_CLIENT_ID=Iv1.abc123def456+GITHUB_CLIENT_SECRET=abc123def456ghi789jkl012mno345pqr678stu+GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----+MIIEpAIBAAKCAQEA...+[Full contents of your private key]+...+-----END RSA PRIVATE KEY-----"+GITHUB_WEBHOOK_SECRET=your-webhook-secret-here+GITHUB_APP_NAME=kaneo-mycompany+```++## Connecting Repositories++Once your environment variables are configured and your backend is restarted, you can connect projects to GitHub repositories.++<Steps>+<Step>+**Navigate to Project Settings**++1. Open your Kaneo project+2. Go to **Project Settings**+3. Find the **GitHub Integration** section+</Step>++<Step>+**Connect Repository**++You have two options to connect a repository:++**Option A: Browse Repositories**+1. Click "Browse Repositories"+2. Select from repositories where your GitHub App is installed+3. Click on the desired repository++**Option B: Manual Entry**+1. Enter the **Repository Owner** (username or organization)+2. Enter the **Repository Name**+3. Click "Verify Installation"+</Step>++<Step>+**Verify and Connect**++1. Kaneo will verify that your GitHub App has access+2. If successful, click "Connect Repository"+3. You should see a green "Connected" status++<Callout type="success">+Once connected, new tasks created in this project will automatically generate GitHub issues!+</Callout>+</Step>+</Steps>++## Testing the Integration++After connecting a repository, test the integration:++<Steps>+<Step>+**Create a Test Task**++Create a new task in your connected Kaneo project with:+- A clear title+- A description+- Set priority and status+</Step>++<Step>+**Check GitHub**++Navigate to your connected GitHub repository and check if:+- A new issue was created+- The issue title starts with `[Kaneo]`+- The issue has appropriate labels (`kaneo`, `priority:*`, `status:*`)+- The issue body contains task details+</Step>++</Steps>++## Advanced Configuration++### Multiple Organizations+If you need to connect repositories from multiple GitHub organizations:++1. Install your GitHub App on each organization+2. Grant appropriate permissions for each organization+3. Each Kaneo project can connect to any repository where your app is installed++### Custom Labels+Currently, Kaneo uses these default labels:+- `kaneo` - All issues created by Kaneo+- `priority:high|medium|low` - Based on task priority+- `status:todo|in-progress|done` - Based on task status++Future versions will support custom label configurations.++---++**Having issues?** Check our [troubleshooting guide](/docs/integrations/github/troubleshooting) for common problems and solutions.\ No newline at end of filediff --git a/apps/docs/content/docs/core/integrations/github/meta.json b/apps/docs/content/docs/core/integrations/github/meta.jsonnew file mode 100644index 000000000..5aed06019--- /dev/null+++ b/apps/docs/content/docs/core/integrations/github/meta.json@@ -0,0 +1,5 @@+{+ "title": "GitHub",+ "pages": ["setup", "configuration", "troubleshooting"],+ "defaultOpen": false+}diff --git a/apps/docs/content/docs/core/integrations/github/setup.mdx b/apps/docs/content/docs/core/integrations/github/setup.mdxnew file mode 100644index 000000000..e65d90479--- /dev/null+++ b/apps/docs/content/docs/core/integrations/github/setup.mdx@@ -0,0 +1,196 @@+---+title: App Setup+description: Learn how to create and configure a GitHub App for Kaneo integration. Step-by-step guide to register your Kaneo instance with GitHub.+---++import { Step, Steps } from 'fumadocs-ui/components/steps';+import { Callout } from 'fumadocs-ui/components/callout';++This guide walks you through creating and configuring a GitHub App to enable the Kaneo integration. **Start here before deploying or configuring your Kaneo instance.**++## Overview++A GitHub App provides secure, granular access to your repositories and allows Kaneo to:+- Create issues automatically when tasks are created+- Access repository metadata for verification+- Receive webhook events for issue synchronization++<Callout type="info">+GitHub Apps are more secure than personal access tokens and provide better permission control.+</Callout>++<Callout type="error">+**Important**: Complete this GitHub App setup **before** deploying Kaneo. You'll need the app credentials during deployment configuration.+</Callout>++## Step 1: Create a GitHub App++<Steps>+<Step>+**Navigate to GitHub App Settings**++Go to [GitHub Developer Settings](https://github.com/settings/developers) and click "New GitHub App".+</Step>++<Step>+**Configure Basic Information**++Fill in the basic app information:++- **GitHub App name**: `kaneo-[your-instance-name]` (must be unique across GitHub)+- **Description**: `Kaneo project management integration`+- **Homepage URL**: Your planned Kaneo instance URL (e.g., `https://kaneo.yourdomain.com`)+- **Webhook URL**: `https://your-kaneo-instance.com/github-integration/webhook`+- **Webhook secret**: Generate a secure random string (save this for later)++<Callout type="warning">+Replace `your-kaneo-instance.com` with your planned Kaneo domain. The webhook URL must be publicly accessible once deployed.+</Callout>+</Step>++<Step>+**Set Repository Permissions**++Configure the following permissions:++| Permission | Access | Purpose |+|------------|---------|---------|+| **Issues** | Read & Write | Create and update issues |+| **Metadata** | Read | Access repository information |+| **Contents** | Read | Access repository metadata |++<Callout type="error">+**Critical**: Make sure to grant **Write** access to Issues - this is required for creating issues automatically.+</Callout>+</Step>++<Step>+**Subscribe to Webhook Events**++**This step is required for proper integration.** Subscribe to these events:++- **Issues** - To track when issues are created, updated, or closed+- **Issue Comments** - To track comments on issues++<Callout type="error">+**Required**: You must subscribe to **Issues** events for the integration to work properly. This enables bidirectional synchronization between Kaneo tasks and GitHub issues.+</Callout>++<Callout type="info">+These webhook events enable real-time synchronization between your Kaneo tasks and GitHub issues.+</Callout>+</Step>++<Step>+**Create the App**++Click "Create GitHub App" to create your app. You'll be redirected to the app settings page.+</Step>+</Steps>++## Step 2: Generate Credentials++<Steps>+<Step>+**Generate and Download Private Key**++1. Scroll down to the "Private keys" section+2. Click "Generate a private key"+3. Download the `.pem` file - you'll need its contents for configuration++<Callout type="warn">+Keep this private key secure! It's used to authenticate your Kaneo instance with GitHub.+</Callout>+</Step>++<Step>+**Note Your App Information**++From the app settings page, note down these important values:++- **App ID** (shown at the top of the page)+- **Client ID** (in the "Basic information" section)+- **Client Secret** (click "Generate a new client secret")+- **Webhook Secret** (the one you created earlier)+- **Private Key** (contents of the downloaded `.pem` file)++<Callout type="info">+You'll need all of these values for the [configuration step](/docs/integrations/github/configuration).+</Callout>+</Step>+</Steps>++## Step 3: Install the App++<Steps>+<Step>+**Install on Your Account/Organization**++1. Go to your GitHub App settings page+2. Click "Install App" in the left sidebar+3. Choose your account or organization+4. Select repositories:+ - **All repositories** (if you want integration available for all repos)+ - **Selected repositories** (choose specific repos)++<Callout type="tip">+You can modify repository access later by going to your [GitHub App installations](https://github.com/settings/installations).+</Callout>+</Step>++<Step>+**Verify Installation**++After installation, you should see your app listed in:+- [Your GitHub App installations](https://github.com/settings/installations)+- The repository's Settings → Integrations & services (for organization repos)+</Step>+</Steps>++## Security Best Practices++### App Configuration+- **Use descriptive names**: Make it clear the app is for Kaneo integration+- **Limit permissions**: Only grant the minimum required permissions+- **Repository scope**: Install only on repositories that need integration++### Credential Management+- **Secure storage**: Store credentials in environment variables or secret management systems+- **Regular rotation**: Generate new private keys periodically+- **Access control**: Limit who has access to the GitHub App settings++## Common Issues++### App Name Already Taken+If your desired app name is taken, try:+- Adding your organization name: `kaneo-mycompany`+- Adding a timestamp: `kaneo-mycompany-2024`+- Using a different naming convention: `mycompany-kaneo`++### Webhook URL Not Accessible+Ensure your Kaneo instance is:+- Publicly accessible on the internet+- Using HTTPS (GitHub requires this for webhooks)+- Not behind authentication that would block GitHub's webhook calls++### Permission Issues+Double-check that you've granted:+- **Write** access to Issues (not just Read)+- **Read** access to Metadata and Contents+- Selected the correct repositories during installation++## Next Steps++Now that your GitHub App is created and configured:++1. **[Deploy Kaneo](/docs/getting-started/deployment)** - Deploy your Kaneo instance with the GitHub App credentials+2. **[Configure GitHub Integration](/docs/integrations/github/configuration)** - Complete the integration setup in your deployed Kaneo instance+3. **[Connect Repositories](/docs/integrations/github/configuration#connecting-repositories)** - Link your projects to GitHub repositories++<Callout type="info">+**Important**: Have your GitHub App credentials ready before deployment. You'll need to set them as environment variables during the deployment process.+</Callout>++---++**Need help?** Check our [troubleshooting guide](/docs/integrations/github/troubleshooting) or ask for help on [Discord](https://discord.gg/rU4tSyhXXU).\ No newline at end of filediff --git a/apps/docs/content/docs/core/integrations/github/troubleshooting.mdx b/apps/docs/content/docs/core/integrations/github/troubleshooting.mdxnew file mode 100644index 000000000..2751e54f8--- /dev/null+++ b/apps/docs/content/docs/core/integrations/github/troubleshooting.mdx@@ -0,0 +1,295 @@+---+title: Troubleshooting+description: Common issues and solutions for GitHub integration. Debug connection problems, permission errors, and webhook issues.+---++import { Callout } from 'fumadocs-ui/components/callout';++This guide helps you diagnose and fix common issues with the GitHub integration.++## Common Issues++### "GitHub App not installed" Error++**Problem**: Verification shows the app isn't installed on the repository.++**Symptoms**:+- Red error message in Kaneo UI+- "Connect Repository" button remains disabled+- Repository doesn't appear in the browser modal++**Solutions**:+1. **Check Installation Scope**+ - Go to [GitHub App installations](https://github.com/settings/installations)+ - Verify your app is installed on the correct account/organization+ - Check if the target repository is included in the installation scope++2. **Reinstall with Broader Access**+ - Edit your app installation+ - Change from "Selected repositories" to "All repositories"+ - Or add the specific repository to the selected list++3. **Verify Repository Ownership**+ - Ensure you're entering the correct repository owner (username/organization)+ - Check that the repository name is spelled correctly+ - Verify the repository exists and you have access to it++<Callout type="tip">+Use the "Browse Repositories" feature in Kaneo to see which repositories your app can access.+</Callout>++### "Missing Permissions" Error++**Problem**: App is installed but lacks required permissions.++**Symptoms**:+- Orange warning in verification+- App appears in installations but can't create issues+- Missing permissions listed in the error message++**Solutions**:+1. **Update App Permissions**+ - Go to your [GitHub App settings](https://github.com/settings/developers)+ - Edit your app and check permissions:+ - **Issues**: Must have **Write** access (not just Read)+ - **Metadata**: Must have **Read** access+ - **Contents**: Must have **Read** access++2. **Update Installation**+ - After changing app permissions, you may need to update the installation+ - Go to [GitHub App installations](https://github.com/settings/installations)+ - Click "Configure" next to your app+ - Review and accept any permission changes++3. **Check Organization Permissions**+ - For organization repositories, ensure the organization allows the app+ - Organization owners may need to approve third-party apps++### "Repository not found" Error++**Problem**: Repository exists but isn't accessible to the app.++**Symptoms**:+- Repository not found in verification+- 404-style errors in logs+- Repository doesn't appear in browse modal++**Solutions**:+1. **Verify Repository Details**+ - Double-check the repository owner and name+ - Ensure there are no typos or extra spaces+ - Check that the repository is public or your app has access to private repos++2. **Check Private Repository Access**+ - Private repositories require explicit app installation+ - Ensure your GitHub App is installed on the repository owner's account+ - Verify the app has permission to access private repositories++3. **Organization Repository Issues**+ - Check if the organization has third-party app restrictions+ - Ensure the app is approved by organization owners+ - Verify the app is installed at the organization level, not just personal account++### Environment Variable Issues++**Problem**: Integration doesn't work after configuration.++**Symptoms**:+- No GitHub issues created when tasks are made+- Authentication errors in logs+- Integration appears configured but doesn't function++**Solutions**:+1. **Verify All Variables Are Set**+ ```bash+ # Check if environment variables are loaded+ echo $GITHUB_APP_ID+ echo $GITHUB_CLIENT_ID+ # etc.+ ```++2. **Check Private Key Format**+ - Ensure `GITHUB_PRIVATE_KEY` includes the full content with proper line breaks+ - The key should start with `-----BEGIN RSA PRIVATE KEY-----`+ - The key should end with `-----END RSA PRIVATE KEY-----`+ - Include all newlines and formatting from the `.pem` file++3. **Restart Backend Service**+ - Environment variable changes require a service restart+ - For Docker Compose: `docker compose restart backend`+ - For Kubernetes: `kubectl rollout restart deployment/kaneo-backend`++4. **Check Log Output**+ - Look for authentication errors on startup+ - Verify the GitHub App ID is recognized+ - Check for private key parsing errors++<Callout type="warning">+Make sure your private key doesn't have any extra characters or missing newlines.+</Callout>++## Webhook Issues++### Webhook Not Receiving Events++**Problem**: GitHub events aren't reaching Kaneo.++**Symptoms**:+- Webhook events listed in GitHub but no logs in Kaneo+- Webhook delivery failures in GitHub App settings++**Solutions**:+1. **Verify Webhook URL**+ - Ensure the URL is publicly accessible: `https://your-domain.com/github-integration/webhook`+ - Test accessibility from external tools like curl or online checkers+ - Verify your domain has proper DNS resolution++2. **Check HTTPS Configuration**+ - GitHub requires HTTPS for webhook endpoints+ - Ensure your SSL certificate is valid and not self-signed+ - Test your webhook endpoint with online SSL checkers++3. **Firewall and Network Issues**+ - Ensure GitHub's IP ranges can reach your server+ - Check if your hosting provider blocks incoming webhooks+ - Verify no authentication middleware is blocking the webhook endpoint++### Webhook Signature Verification Fails++**Problem**: Webhooks reach Kaneo but signature verification fails.++**Symptoms**:+- "Invalid signature" errors in logs+- Webhook events rejected with 400 status++**Solutions**:+1. **Verify Webhook Secret**+ - Ensure `GITHUB_WEBHOOK_SECRET` matches exactly what you set in the GitHub App+ - Check for extra spaces or characters+ - The secret is case-sensitive++2. **Check Secret Configuration**+ - In GitHub App settings, verify the webhook secret is set+ - If you changed the secret, update the environment variable and restart+ - Generate a new secret if there are persistent issues++## Testing and Debugging++### Testing the Integration++Follow these steps to systematically test your integration:++1. **Verify Environment Variables**+ ```bash+ # Check that all required variables are set (don't print private key!)+ echo "App ID: $GITHUB_APP_ID"+ echo "Client ID: $GITHUB_CLIENT_ID"+ echo "Webhook Secret: [REDACTED]"+ echo "App Name: $GITHUB_APP_NAME"+ ```++2. **Test Repository Access**+ - Use the "Browse Repositories" feature in Kaneo+ - Verify your target repository appears in the list+ - Try connecting a test repository first++3. **Create a Test Task**+ - Create a simple task in your connected project+ - Check GitHub immediately for the new issue+ - Verify the issue format and labels are correct++4. **Check Backend Logs**+ Look for these log messages:+ ```+ ✅ GitHub issue created: { issueNumber: 42, issueUrl: "...", taskId: "...", repository: "..." }+ ❌ Failed to create GitHub issue: [error details]+ ✅ Task created: { taskId: "...", title: "...", projectId: "..." }+ ```++### Log Analysis++**Successful Integration Logs**:+```+Task created: { taskId: "task_123", title: "Fix bug", projectId: "proj_456" }+Creating GitHub issue for repository: owner/repo+GitHub issue created: { issueNumber: 42, issueUrl: "https://github.com/owner/repo/issues/42" }+```++**Common Error Patterns**:+```+❌ No active GitHub integration found for project: proj_456+❌ Failed to create GitHub issue: HttpError: Bad credentials+❌ Repository not found: owner/nonexistent-repo+❌ App installation not found for repository: owner/repo+```++### GitHub App Diagnostics++Use GitHub's built-in tools to diagnose issues:++1. **App Installation Page**+ - Visit [GitHub App installations](https://github.com/settings/installations)+ - Check which repositories your app can access+ - Review granted permissions++2. **Webhook Delivery Logs**+ - In your GitHub App settings, check the "Advanced" tab+ - Review recent webhook deliveries and their status codes+ - Look for failed deliveries or error responses++3. **Repository Integration Status**+ - Go to your repository's Settings → Integrations & services+ - Verify your app appears in the list+ - Check the app's permissions and access++## Getting Help++If you're still experiencing issues:++### Before Asking for Help++1. **Check Your Setup**+ - Verify all environment variables are correct+ - Ensure your GitHub App has the right permissions+ - Test with a simple repository first++2. **Gather Information**+ - Note the exact error messages+ - Check both Kaneo logs and GitHub webhook delivery logs+ - Document your environment (Docker, Kubernetes, etc.)++3. **Test Basic Functionality**+ - Try creating a task without GitHub integration+ - Verify your Kaneo instance is working normally+ - Test with different repositories if possible++### Support Channels++- **[Discord Community](https://discord.gg/rU4tSyhXXU)** - Real-time help from the community+- **[GitHub Issues](https://github.com/usekaneo/kaneo/issues)** - Report bugs or request features+- **[Documentation](/docs)** - Review setup guides and troubleshooting++### What to Include in Support Requests++1. **Environment Details**+ - Kaneo version+ - Deployment method (Docker, Kubernetes, etc.)+ - Operating system++2. **Error Information**+ - Exact error messages+ - Screenshots of the issue+ - Relevant log entries++3. **Configuration Details**+ - Which environment variables you've set (don't share secret values!)+ - GitHub App permissions you've granted+ - Repository details (without sharing sensitive info)++<Callout type="info">+When sharing logs or error messages, always redact sensitive information like private keys, secrets, or access tokens.+</Callout>++---++**Still stuck?** The Kaneo community is here to help! Join our [Discord](https://discord.gg/rU4tSyhXXU) for real-time support.\ No newline at end of filediff --git a/apps/docs/content/docs/core/integrations/meta.json b/apps/docs/content/docs/core/integrations/meta.jsonnew file mode 100644index 000000000..141741b99--- /dev/null+++ b/apps/docs/content/docs/core/integrations/meta.json@@ -0,0 +1,6 @@+{+ "title": "Integrations",+ "icon": "Plug",+ "pages": ["github"],+ "defaultOpen": false+}diff --git a/apps/docs/content/docs/core/meta.json b/apps/docs/content/docs/core/meta.jsonnew file mode 100644index 000000000..0924460c8--- /dev/null+++ b/apps/docs/content/docs/core/meta.json@@ -0,0 +1,4 @@+{+ "title": "Docs",+ "root": true+}diff --git a/apps/docs/content/docs/core/reverse-proxy/meta.json b/apps/docs/content/docs/core/reverse-proxy/meta.jsonnew file mode 100644index 000000000..f99a03c3a--- /dev/null+++ b/apps/docs/content/docs/core/reverse-proxy/meta.json@@ -0,0 +1,6 @@+{+ "title": "Reverse Proxy",+ "icon": "Server",+ "pages": ["index", "nginx", "traefik"],+ "defaultOpen": true+}diff --git a/apps/docs/content/docs/core/reverse-proxy/nginx.mdx b/apps/docs/content/docs/core/reverse-proxy/nginx.mdxnew file mode 100644index 000000000..724126a0a--- /dev/null+++ b/apps/docs/content/docs/core/reverse-proxy/nginx.mdx@@ -0,0 +1,78 @@+---+title: Nginx+description: Nginx is a web server that can be used as a reverse proxy.+---++## Overview++This guide explains how to deploy Kaneo using Nginx as a reverse proxy. This setup is ideal for production environments where you want to expose Kaneo through a domain name with HTTPS.++## Prerequisites++- A domain name+- A SSL certificate+- A Nginx web server++## Installation++The first step is to make sure nginx is installed and running.++```bash+sudo apt update+sudo apt install nginx+```++## Configuration++The next step is to configure Nginx to proxy requests to the Kaneo services. We will create two servers, one for the web application and one for the API.++1. Create a new file in the `/etc/nginx/sites-available/kaneo.conf` directory.++```nginx title="kaneo.conf"+server {+ listen 80;+ server_name kaneo.your-domain.com;++ location / {+ proxy_pass http://localhost:5173;+ proxy_set_header Host $host;+ proxy_set_header X-Real-IP $remote_addr;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ }+}++server {+ listen 80;+ server_name kaneo-api.your-domain.com;++ location / {+ proxy_pass http://localhost:1337;+ proxy_set_header Host $host;+ proxy_set_header X-Real-IP $remote_addr;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ }+}+```++2. Enable the configuration by creating a symlink to the `sites-enabled` directory.++```bash+sudo ln -s /etc/nginx/sites-available/kaneo.conf /etc/nginx/sites-enabled/+```++3. Test the configuration.++```bash+sudo nginx -t+```++4. Restart Nginx to apply the changes.++```bash+sudo systemctl restart nginx+```++## Key points++- This configuration is for a single server, if you want to use a load balancer, you need to configure it accordingly.+- This configuration is for a single domain, if you want to use a subdomain, you need to configure it accordingly.\ No newline at end of filediff --git a/apps/docs/content/docs/core/social-providers/custom-oauth.mdx b/apps/docs/content/docs/core/social-providers/custom-oauth.mdxnew file mode 100644index 000000000..dcdfaf51c--- /dev/null+++ b/apps/docs/content/docs/core/social-providers/custom-oauth.mdx@@ -0,0 +1,170 @@+---+title: Custom OAuth/OIDC+description: Configure Kaneo with your custom OpenID Connect (OIDC) provider.+---++## Overview++Kaneo supports custom OAuth 2.0 and OpenID Connect (OIDC) providers, allowing you to integrate with any standards-compliant identity provider such as Keycloak, Auth0, Okta, Azure AD, or self-hosted solutions like Pocket ID.++## Configuration++To configure a custom OAuth/OIDC provider, you need to set the following environment variables in your `.env` file:++### Required Variables++| Variable | Description | Example |+|----------|-------------|---------|+| `CUSTOM_OAUTH_CLIENT_ID` | OAuth client ID from your provider | `2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0` |+| `CUSTOM_OAUTH_CLIENT_SECRET` | OAuth client secret from your provider | `NzDjplDsdQyP062wTmkZ8kyiaziBag0N` |+| `CUSTOM_OAUTH_AUTHORIZATION_URL` | Authorization endpoint URL | `https://id.example.com/authorize` |+| `CUSTOM_OAUTH_TOKEN_URL` | Token exchange endpoint URL | `https://id.example.com/api/oidc/token` |+| `CUSTOM_OAUTH_USER_INFO_URL` | User info endpoint URL | `https://id.example.com/api/oidc/userinfo` |++### Optional Variables++| Variable | Description | Default |+|----------|-------------|---------|+| `CUSTOM_OAUTH_DISCOVERY_URL` | OpenID Connect discovery document URL | - |+| `CUSTOM_OAUTH_SCOPES` | Comma-separated list of OAuth scopes | `profile,email` |+| `CUSTOM_OAUTH_RESPONSE_TYPE` | OAuth response type | `code` |+| `CUSTOM_AUTH_PKCE` | Enable/disable PKCE (Proof Key for Code Exchange) | `true` |++## Setup Steps++### 1. Configure Your OAuth Provider++First, create an OAuth 2.0 or OIDC application in your identity provider:++1. Log in to your identity provider's admin console+2. Create a new OAuth 2.0 or OIDC application+3. Set the redirect URI to: `{KANEO_API_URL}/api/auth/callback/custom`+ - Example: `https://api.kaneo.example.com/api/auth/callback/custom`+4. Copy the client ID and client secret+5. Note the authorization, token, and userinfo endpoint URLs++### 2. Set Environment Variables++Add the following to your `.env` file:++```bash+# Custom OAuth/OIDC Configuration+CUSTOM_OAUTH_CLIENT_ID=your-client-id+CUSTOM_OAUTH_CLIENT_SECRET=your-client-secret+CUSTOM_OAUTH_AUTHORIZATION_URL=https://your-idp.com/authorize+CUSTOM_OAUTH_TOKEN_URL=https://your-idp.com/oauth/token+CUSTOM_OAUTH_USER_INFO_URL=https://your-idp.com/oauth/userinfo++# Optional: Use discovery URL for automatic configuration+CUSTOM_OAUTH_DISCOVERY_URL=https://your-idp.com/.well-known/openid-configuration++# Optional: Customize scopes+CUSTOM_OAUTH_SCOPES=profile,email,openid++# Optional: Disable PKCE if your provider doesn't support it+CUSTOM_AUTH_PKCE=false+```++### 3. Restart Services++After updating the environment variables, restart your Kaneo services:++```bash+docker compose restart+```++## Example Configurations++### Pocket ID++```bash+CUSTOM_OAUTH_CLIENT_ID=2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0+CUSTOM_OAUTH_CLIENT_SECRET=NzDjplDsdQyP062wTmkZ8kyiaziBag0N+CUSTOM_OAUTH_AUTHORIZATION_URL=https://4c6332d2.demo.pocket-id.org/authorize+CUSTOM_OAUTH_TOKEN_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/token+CUSTOM_OAUTH_USER_INFO_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/userinfo+CUSTOM_OAUTH_DISCOVERY_URL=https://4c6332d2.demo.pocket-id.org/.well-known/openid-configuration+CUSTOM_OAUTH_SCOPES=profile,email+```++### Keycloak++```bash+CUSTOM_OAUTH_CLIENT_ID=kaneo-client+CUSTOM_OAUTH_CLIENT_SECRET=your-secret-here+CUSTOM_OAUTH_DISCOVERY_URL=https://keycloak.example.com/realms/your-realm/.well-known/openid-configuration+CUSTOM_OAUTH_SCOPES=openid,profile,email+```++### Auth0++```bash+CUSTOM_OAUTH_CLIENT_ID=your-client-id+CUSTOM_OAUTH_CLIENT_SECRET=your-client-secret+CUSTOM_OAUTH_AUTHORIZATION_URL=https://your-tenant.auth0.com/authorize+CUSTOM_OAUTH_TOKEN_URL=https://your-tenant.auth0.com/oauth/token+CUSTOM_OAUTH_USER_INFO_URL=https://your-tenant.auth0.com/userinfo+CUSTOM_OAUTH_SCOPES=openid,profile,email+```++## Usage++Once configured, users will see a "Continue with OIDC" button on the sign-in page. The system will automatically remember the last used login method for each user.++## Troubleshooting++### "Invalid code verifier" Error++This error typically indicates a PKCE configuration issue. Try setting:++```bash+CUSTOM_AUTH_PKCE=false+```++Some OAuth providers don't support PKCE or have it disabled by default.++### Missing User Information++Ensure your OAuth scopes include at least `profile` and `email`:++```bash+CUSTOM_OAUTH_SCOPES=profile,email+```++Some providers require `openid` scope as well:++```bash+CUSTOM_OAUTH_SCOPES=openid,profile,email+```++### Redirect URI Mismatch++Verify that your redirect URI in the OAuth provider matches exactly:++```+{KANEO_API_URL}/api/auth/callback/custom+```++For example, if `KANEO_API_URL=https://api.kaneo.example.com`, the redirect URI should be:++```+https://api.kaneo.example.com/api/auth/callback/custom+```++## Discovery URL++If your provider supports OpenID Connect, you can use the discovery URL to automatically configure most settings:++```bash+CUSTOM_OAUTH_DISCOVERY_URL=https://your-idp.com/.well-known/openid-configuration+```++This will automatically discover the authorization, token, and userinfo endpoints. However, you still need to provide the client ID and secret.++## Security Notes++- Always use HTTPS in production+- Keep your client secret secure and never commit it to version control+- Enable PKCE when possible for enhanced security+- Use the most restrictive scopes necessary for your use case+diff --git a/apps/docs/content/docs/core/social-providers/github.mdx b/apps/docs/content/docs/core/social-providers/github.mdxnew file mode 100644index 000000000..7b4b78777--- /dev/null+++ b/apps/docs/content/docs/core/social-providers/github.mdx@@ -0,0 +1,22 @@+---+title: GitHub+description: GitHub is a social provider for Kaneo.+---++## Overview++GitHub is a social provider for Kaneo. It allows users to sign in to Kaneo using their GitHub account.++## Configuration++1. Go to the [GitHub Developer Settings](https://github.com/settings/developers/).+2. Create a new OAuth app.+3. Set the redirect URI to `KANEO_API_URL/api/auth/callback/github`.+4. Copy the client ID and client secret.+5. Set the `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` environment variables.++For more information on what your `KANEO_API_URL` is, see the [Environment variables](/docs/installation/environment-variables#github-sso--integration) page.++## Usage++Once you have configured the social provider, you can sign in to Kaneo using your GitHub account.\ No newline at end of filediff --git a/apps/docs/content/docs/core/social-providers/google.mdx b/apps/docs/content/docs/core/social-providers/google.mdxnew file mode 100644index 000000000..6eb977246--- /dev/null+++ b/apps/docs/content/docs/core/social-providers/google.mdx@@ -0,0 +1,25 @@+---+title: Google+description: Google is a social provider for Kaneo.+---++## Overview++Google is a social provider for Kaneo. It allows users to sign in to Kaneo using their Google account.++## Configuration++1. Go to the [Google Cloud Console](https://console.cloud.google.com/).+2. Create a new project.+3. Enable the Google Sign In API.+4. Create a new OAuth client ID.+5. Set the redirect URI to `KANEO_API_URL/api/auth/callback/google`.+6. Copy the client ID and client secret.+7. Set the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables.+++For more information on what your `KANEO_API_URL` is, see the [Environment variables](/docs/installation/environment-variables#google-sso--integration) page.++## Usage++Once you have configured the social provider, you can sign in to Kaneo using your Google account.\ No newline at end of filediff --git a/apps/docs/content/docs/core/social-providers/meta.json b/apps/docs/content/docs/core/social-providers/meta.jsonnew file mode 100644index 000000000..6e55140e8--- /dev/null+++ b/apps/docs/content/docs/core/social-providers/meta.json@@ -0,0 +1,6 @@+{+ "title": "Social Providers",+ "icon": "Users",+ "pages": ["github", "google", "custom-oauth"],+ "defaultOpen": true+}