Getting Started

SmartyPants has both backend and frontend components. We have made it easy for everyone to get started with SmartyPants.

Installation

Prerequisites

Before installing SmartyPants, ensure you have a PostgreSQL database with the pgvector extension enabled. You can use the following Docker command to set up a compatible database:

docker run -d \
  --name smarty-pants-postgresql \
  -e POSTGRES_DB=<your_db_name> \
  -e POSTGRES_USER=<your_db_user> \
  -e POSTGRES_PASSWORD=<your_db_password> \
  -p <your_db_port>:5432 \
  ankane/pgvector

Method 1: Using Docker

Before proceeding, check the Releases page for the latest version number. Replace <version> in the following commands with the latest release version.

Backend Installation

1. Pull the backend Docker image:

docker pull ghcr.io/shaharia-lab/smarty-pants-backend:<version>

2. Run the backend container:

docker run -d \
  --name smarty-pants-backend \
  -p 8080:8080 \
  -p 2223:2223 \
  -e DB_HOST=<your_db_host> \
  -e DB_PORT=<your_db_port> \
  -e DB_USER=<your_db_user> \
  -e DB_PASS=<your_db_password> \
  -e DB_NAME=<your_db_name> \
  ghcr.io/shaharia-lab/smarty-pants-backend:<version>

Replace <your_db_host>, <your_db_port>, <your_db_user>, <your_db_password>, and <your_db_name> with your actual database connection details.

Frontend Installation

The frontend Docker image is pre-built with a default backend API endpoint of http://localhost:8080. If this default setting works for your setup, you can simply pull and run the pre-built image. If you need to use a different backend API endpoint, you'll need to build the Docker image yourself.

Option 1: Using the pre-built image (default backend: http://localhost:8080)

1. Pull the frontend Docker image:

docker pull ghcr.io/shaharia-lab/smarty-pants-frontend:<version>

2. Run the frontend container:

docker run -d \
  --name smarty-pants-frontend \
  -p 3000:3000 \
  ghcr.io/shaharia-lab/smarty-pants-frontend:<version>

Option 2: Building a custom image (for a different backend API endpoint)

If you need to use a different backend API endpoint, you'll need to build the Docker image yourself. You can do this using either standard Docker build or Docker Buildx.

1. Clone the repository:

git clone https://github.com/shaharia-lab/smarty-pants.git
cd smarty-pants

2. Build the image using Docker:

docker build \
  --build-arg NEXT_PUBLIC_API_BASE_URL=http://your-custom-backend-url.com \
  -t smarty-pants-frontend:custom \
  -f frontend/smarty-pants/Dockerfile \
  frontend/smarty-pants

Or, using Docker Buildx (which allows building directly from the GitHub repository):

docker buildx build \
  https://github.com/shaharia-lab/smarty-pants.git#main:frontend/smarty-pants \
  --build-arg NEXT_PUBLIC_API_BASE_URL=http://your-custom-backend-url.com \
  -t smarty-pants-frontend:custom \
  --load

Replace http://your-custom-backend-url.com with your actual backend API endpoint.

3. Run your custom-built frontend container:

docker run -d \
  --name smarty-pants-frontend \
  -p 3000:3000 \
  smarty-pants-frontend:custom

Note: When building a custom image, the NEXT_PUBLIC_API_BASE_URL is baked into the image at build time due to Next.js limitations with runtime environment variables. You cannot change this value at runtime without rebuilding the image.

Using a specific version or tag

If you want to build from a specific version or tag of the repository, modify the Buildx command like this:

docker buildx build \
  https://github.com/shaharia-lab/smarty-pants.git#refs/tags/<tag-name>:frontend/smarty-pants \
  --build-arg NEXT_PUBLIC_API_BASE_URL=http://your-custom-backend-url.com \
  -t smarty-pants-frontend:custom \
  --load

Replace <tag-name> with the specific tag you want to use.

Method 2: Using Docker Compose

1. Create a file named docker-compose.yml in your project directory with the following content:

version: '3.8'

services:
  database:
    image: ankane/pgvector
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: pass
    ports:
      - "5432:5432"

  backend:
    image: ghcr.io/shaharia-lab/smarty-pants-backend:<version>
    ports:
      - "8080:8080"
      - "2223:2223"
    environment:
      DB_HOST: database
      DB_PORT: 5432
      DB_USER: app
      DB_PASS: pass
      DB_NAME: app
    depends_on:
      - database

  frontend:
    image: ghcr.io/shaharia-lab/smarty-pants-frontend:<version>
    ports:
      - "3000:3000"
    depends_on:
      - backend

Replace <version> with the latest release version from the Releases page.

2. Run the following command in the same directory as your docker-compose.yml file:

docker-compose up -d

This command will start all the services defined in the docker-compose.yml file: the PostgreSQL database, the backend, and the frontend.

Accessing the Application

After installation, you can access:

• The frontend application at http://localhost:3000
• The backend API at http://localhost:8080

Verify Installation

To ensure that both the frontend and backend components are working correctly, you can perform the following checks:

Frontend Verification

1. Open a web browser and navigate to:

   http://localhost:3000/auth
2. You should see the login page of the SmartyPants application.

Backend Verification

1. To verify the backend, you can use a web browser or a tool like curl to send a request to the following endpoint:

   http://localhost:8080/system/ping
2. The response should be:

   pong

If you can see the login page and receive the "pong" response, it means both your frontend and backend are installed and running correctly.

Troubleshooting

If you encounter any issues during installation or while running the application, please check the following:

1. Ensure all required ports (5432, 8080, 2223, 3000) are available and not being used by other applications.
2. Verify that your Docker installation is up-to-date and running correctly.
3. Check the logs of each container for any error messages:

   docker logs smarty-pants-backend
   docker logs smarty-pants-frontend

For further assistance:

• Check if your issue has already been reported by visiting our GitHub Issues page from here

• If you can't find a solution to your problem, please submit a new issue on our GitHub repository from here When submitting a new issue, please provide detailed information about your setup, the steps to reproduce the problem, and any error messages you've encountered.

We appreciate your contributions to improving SmartyPants!