Skip to content

SETUP.md

Latest commit

 

History

History
467 lines (291 loc) · 13.7 KB

SETUP.md

File metadata and controls

467 lines (291 loc) · 13.7 KB

KoalaCards Setup Guide

This guide will help you set up the project on your local machine. Please follow the instructions carefully to ensure a smooth setup experience.

Note: This project is currently in a semi-public alpha phase. If you encounter any issues or have questions, feel free to raise an issue on GitHub.

Table of Contents

  1. Prerequisites
  2. Clone the Repository
  3. Set Up Environment Variables
  4. Configure Cloud Services
  5. Run the Application
  6. Accessing the Application
  7. Troubleshooting
  8. Additional Resources

Prerequisites

Before setting up KoalaCards, ensure that your system meets the following prerequisites.

1.1 Install Node.js

KoalaCards requires Node.js to run. It's recommended to use the latest Long-Term Support (LTS) version.

  1. Download Node.js:

    Visit the official Node.js website and download the installer for your operating system.

  2. Install Node.js:

    Run the downloaded installer and follow the on-screen instructions.

  3. Verify Installation:

    Open your terminal or command prompt and run:

    node -v
npm -v

    You should see the installed versions of Node.js and npm.

    v22.x.x
10.x.x

    Note: KoalaCards has been tested with Node.js v22. It's recommended to use this version to avoid compatibility issues.

1.2 Install Docker

Docker is essential for containerizing the application and its dependencies.

  1. Download Docker:

    Visit the official Docker website and download Docker Desktop for your operating system.

  2. Install Docker:

    Run the downloaded installer and follow the installation prompts.

  3. Verify Installation:

    Open your terminal or command prompt and run:

    docker --version

    You should see the installed Docker version.

    Docker version 24.x.x, build xxxxxxx

1.3 Install Docker Compose

Docker Compose is used to manage multi-container Docker applications.

  1. Check if Docker Compose is Installed:

    Docker Desktop typically includes Docker Compose. Verify by running:

    docker-compose --version

    You should see the installed Docker Compose version.

    docker-compose version 2.x.x, build xxxxxxx

  2. If Not Installed, Install Docker Compose:

    Follow the official Docker Compose installation guide for your operating system.

1.4 (Optional) Install TailScale

TailScale is used for secure networking and is required for magic link sign-in functionality in KoalaCards.

Note: If you intend to use the magic link sign-in feature, installing TailScale is mandatory. Otherwise, it's optional.

  1. Download TailScale:

    Visit the official TailScale website and download the appropriate installer for your operating system.

  2. Install TailScale:

    Run the downloaded installer and follow the installation prompts.

  3. Authenticate TailScale:

    After installation, launch TailScale and follow the on-screen instructions to authenticate and connect to your TailScale network.

Clone the Repository

To get started, clone the KoalaCards repository from GitHub.

  1. Open Terminal or Command Prompt:

  2. Clone the Repository:

    git clone git@github.com:RickCarlino/KoalaCards.git

    Note: Ensure you have SSH access to GitHub. If you prefer HTTPS, use:

    git clone https://github.com/RickCarlino/KoalaCards.git

  3. Navigate to the Project Directory:

    cd KoalaCards

Set Up Environment Variables

Environment variables are crucial for configuring the application. Follow these steps to set them up.

  1. Copy the Example Environment File:

    cp example.env .env

  2. Open the .env File:

    Use your preferred text editor to open the .env file.

    nano .env

    Replace nano with your editor of choice (e.g., vim, code for VS Code).

  3. Fill Out the Required Environment Variables:

    Update the .env file with your specific configurations. Below are the key variables you need to set:

    # Database Configuration
POSTGRES_USER=prisma
POSTGRES_PASSWORD=your_password
POSTGRES_DB=prisma_dev
POSTGRES_URI=postgres://prisma:your_password@db:5432/prisma_dev

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key

# Google Cloud Configuration
GOOGLE_APPLICATION_CREDENTIALS=./path-to-your-gcs-credentials.json

# Optional Reader integration: Instapaper
INSTAPAPER_CONSUMER_KEY=your_instapaper_consumer_key
INSTAPAPER_CONSUMER_SECRET=your_instapaper_consumer_secret

    INSTAPAPER_CONSUMER_KEY and INSTAPAPER_CONSUMER_SECRET are optional. If they are not set, only /reader/instapaper actions are disabled.

    Security Tip: Never commit your .env file to version control. Ensure it's listed in your .gitignore.

  4. Save and Close the .env File:

    If using nano, press CTRL + O to save and CTRL + X to exit.

Configure Cloud Services

KoalaCards integrates with external cloud services like OpenAI, Google Cloud, and Google OAuth. Follow the steps below to configure these services.

4.1 OpenAI API Key

  1. Create an OpenAI Account:

    If you don't have one, sign up at OpenAI.

  2. Generate an API Key:

    • Navigate to the API Keys section in your OpenAI dashboard.
    • Click on "Create new secret key".
    • Copy the generated API key.

  3. Update the .env File:

    Open the .env file and set the OPENAI_API_KEY:

    OPENAI_API_KEY=sk-your-openai-api-key

    Security Tip: Keep your API keys secure and avoid sharing them publicly.

4.2 Google Cloud Service Account

  1. Create a Google Cloud Account:

    If you don't have one, sign up at Google Cloud.

  2. Create a New Project:

    • Navigate to the Google Cloud Console.
    • Click on "Select a project" and then "New Project".
    • Enter a project name and click "Create".

  3. Enable Required APIs:

    • Go to APIs & Services > Library in the Google Cloud Console.
    • Search for and enable the following APIs:
      • Cloud Speech-to-Text API
      • Cloud Text-to-Speech API

  4. Create a Service Account:

    • Navigate to APIs & Services > Credentials.
    • Click on "Create Credentials" and select "Service Account".
    • Enter a name and description for the service account.
    • Assign the necessary roles (e.g., "Cloud Speech Client", "Cloud Text-to-Speech Client").
    • Click "Done".

  5. Generate a JSON Key for the Service Account:

    • In the Service Accounts list, find your newly created service account.
    • Click on the three dots under Actions and select "Manage Keys".
    • Click "Add Key" > "Create new key" > "JSON" > "Create".
    • A JSON file will be downloaded to your machine. Keep this file secure.

  6. Update the .env File:

    Place the downloaded JSON credentials file in the project directory (e.g., ./credentials/gcs.json) and update the .env file:

    GOOGLE_APPLICATION_CREDENTIALS=./credentials/gcs.json

    Security Tip: Do not commit your credentials file to version control. Ensure it's listed in your .gitignore.

4.3 Google OAuth for Sign-In

KoalaCards supports Google Sign-In as an authentication method. Follow these steps to set it up:

  1. Use the Same Google Cloud Project:

    Use the same project you created in the previous step or create a new one specifically for authentication.

  2. Configure OAuth Consent Screen:

    • In the Google Cloud Console, go to APIs & Services > OAuth consent screen.
    • Select the appropriate user type (External for testing or Internal for organization-only use).
    • Fill in the required information:
      • App name: KoalaCards
      • User support email: Your email address
      • Developer contact information: Your email address
    • Click Save and Continue.
    • Add the necessary scopes (typically .../auth/userinfo.email and .../auth/userinfo.profile).
    • Click Save and Continue and complete the setup.

  3. Create OAuth Client ID:

    • Go to APIs & Services > Credentials.
    • Click Create Credentials > OAuth client ID.
    • Select Web application as the application type.
    • Add a name for your OAuth client.
    • Add your domain to Authorized JavaScript origins (e.g., http://localhost:3000 for local development).
    • Add your callback URL to Authorized redirect URIs (e.g., http://localhost:3000/api/auth/callback/google for local development).
    • Click Create.
    • Note your Client ID and Client Secret.

  4. Update the .env File:

    Add the Google OAuth credentials to your .env file:

    GOOGLE_CLIENT_ID="your-client-id"
GOOGLE_CLIENT_SECRET="your-client-secret"

    Note: For production, make sure to update the authorized origins and redirect URIs with your production domain.

Run the Application

With all configurations in place, you can now run KoalaCards using Docker Compose.

  1. Ensure Docker is Running:

    Make sure Docker Desktop is up and running on your machine.

  2. Build and Start the Services:

    From the project root directory, run:

    docker-compose up -d --build
    • -d: Runs the containers in detached mode (in the background).
    • --build: Rebuilds the images if there are any changes in the Dockerfile or dependencies.

  3. Verify the Services are Running:

    docker-compose ps

    You should see both app and db services running.

  4. Apply Database Migrations:

    The entrypoint.sh script automatically handles migrations when the app container starts. To manually run migrations, you can execute:

    docker-compose exec app npx prisma migrate deploy

    For hosted environments (for example Northflank), prefer running migrations in a separate deploy/release step:

    npm run db:migrate:deploy

    Then run the app with:

    npm run start:no-migrate

  5. Access Prisma Studio (Optional):

    Prisma Studio provides a visual interface to interact with your database.

    docker-compose exec app npx prisma studio

    Open the provided URL in your browser to access Prisma Studio.

Accessing the Application

Once the application is running, you can access it via your web browser.

  1. Open Your Browser:

  2. Navigate to:

    http://localhost:3000

Troubleshooting

If you encounter any issues during setup or while running the application, consider the following steps:

  1. Check Container Logs:

    View logs for all services:

    docker-compose logs -f

    To view logs for a specific service (e.g., app):

    docker-compose logs -f app

  2. Restart Services:

    Sometimes, restarting the services can resolve transient issues.

    docker-compose restart

  3. Rebuild Containers:

    If you've made changes to the Dockerfile or dependencies, rebuild the containers.

    docker-compose up -d --build

  4. Verify Environment Variables:

    Ensure that all required environment variables in the .env file are correctly set and that sensitive information like API keys and credentials are accurate.

  5. Check Docker Resources:

    Ensure that Docker has sufficient resources (CPU, memory) allocated. You can adjust these settings in Docker Desktop under Settings > Resources.

  6. Ensure Network Connectivity:

    If using TailScale, verify that it's properly installed and connected. This is essential for the magic link sign-in feature.

  7. Reset Migrations (Development Only):

    If migrations are out of sync, you can reset them. Warning: This will delete all data in the database.

    docker-compose exec app npx prisma migrate reset

  8. Seek Help:

    If problems persist, raise an issue on GitHub with detailed information about the issue.

Additional Resources

These instructions may be out of date. Please raise an issue if things don't work!