### Project Setup and Start

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Commands to set up the Sure project locally, including copying environment variables, installing gems, setting up the database, and starting the development server.

```shell
cd sure
cp .env.example .env
bundle install
bin/rails db:setup
bin/dev
```

--------------------------------

### Initial Project Setup

Source: https://github.com/we-promise/sure/blob/main/CLAUDE.md

Performs the complete initial setup for the project, including installing dependencies and preparing the database. Run this after cloning the repository.

```bash
bin/setup
```

--------------------------------

### Quickstart Example: Sentinel HA Redis

Source: https://github.com/we-promise/sure/blob/main/charts/sure/README.md

Configuration for installing the OT Redis Operator and managing Redis HA with Sentinel, including persistence and authentication.

```yaml
redisOperator:
  enabled: true              # install operator subchart (or leave false if already installed cluster-wide)
  operator:
    resources:               # optional: keep the operator light on small k3s nodes
      requests:
        cpu: 50m
        memory: 128Mi
      limits:
        cpu: 100m
        memory: 256Mi
  managed:
    enabled: true            # render Redis CRs for in-cluster Redis
  mode: sentinel             # enables RedisSentinel CR in addition to RedisReplication
  sentinel:
    enabled: true            # must be true when mode=sentinel
    masterGroupName: mymaster
  name: ""                   # defaults to <fullname>-redis
  replicas: 3
  auth:
    existingSecret: sure-secrets
    passwordKey: redis-password
  persistence:
    className: longhorn
    size: 8Gi
```

--------------------------------

### Local Development Setup for Sure

Source: https://github.com/we-promise/sure/blob/main/README.md

Steps to set up the Sure application for local development, including installing dependencies and starting the development server. Optionally loads demo data.

```shell
cd sure
cp .env.local.example .env.local
bin/setup
bin/dev

# Optionally, load demo data
rake demo_data:default
```

--------------------------------

### Download .env.example

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md

Use this command to download the example environment file as a starting point for your configuration.

```bash
curl -o .env https://raw.githubusercontent.com/we-promise/sure/main/.env.example
```

--------------------------------

### Install PostgreSQL and Start Service

Source: https://github.com/we-promise/sure/wiki/Windows-Dev-Setup-Guide

Installs PostgreSQL and starts it as a service on Debian-based systems.

```shell
sudo apt install postgresql libpq-dev

sudo service postgresql start
```

--------------------------------

### Start Development Server (Rails, Sidekiq, Tailwind CSS)

Source: https://github.com/we-promise/sure/blob/main/CLAUDE.md

Use this command to start all essential development services simultaneously. Ensure all dependencies are installed before running.

```bash
bin/dev
```

--------------------------------

### Server Setup and Security on Hetzner Cloud

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Installs essential packages, Docker, Docker Compose, configures the firewall, and sets up fail2ban for SSH protection. Ensure to replace YOUR_SERVER_IP and your_username with your actual details.

```bash
# Connect to your server (replace with your server's IP)
ssh root@YOUR_SERVER_IP

# Update the system
apt update && apt upgrade -y

# Install essential packages
apt install -y curl wget git ufw fail2ban

# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

# Install Docker Compose
curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
chmod +x /usr/local/bin/docker-compose

# Add your user to docker group (replace 'your_username' with your actual username)
# If you are using root, you can skip this step
if [ "$(whoami)" != "root" ]; then
    usermod -aG docker "$(whoami)"
fi

# Configure firewall
ufw allow ssh
ufw allow 80
ufw allow 443
ufw --force enable

# Configure fail2ban for SSH protection
systemctl enable fail2ban
systemctl start fail2ban
```

--------------------------------

### Install PostgreSQL

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Installs the PostgreSQL database server using Homebrew.

```shell
brew install postgresql
```

--------------------------------

### PostgreSQL User Authentication Setup

Source: https://github.com/we-promise/sure/wiki/Linux-Dev-Setup-Guide

Guides through setting a password for the PostgreSQL 'postgres' user and adding it to the .env file. This is crucial for resolving authentication issues.

```sh
sudo -i -u postgres
psql
\password postgres
<follow instructions to set password for 'postgres' user
exit
exit
```

```dotenv
# Database Configuration
DB_HOST=localhost
POSTGRES_PASSWORD=<new password>
POSTGRES_USER=postgres
```

--------------------------------

### Download Example MCP Configuration

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/mcp.md

Download the example configuration files for Pipelock and MCP. These files are essential for setting up a secure production environment.

```bash
curl -o compose.ai.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.ai.yml
curl -o pipelock.example.yaml https://raw.githubusercontent.com/we-promise/sure/main/pipelock.example.yaml
```

--------------------------------

### Qdrant Docker Compose Example

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Example Docker Compose configuration for running Qdrant alongside the Sure application, specifying environment variables and volumes.

```yaml
services:
  sure:
    environment:
      - VECTOR_STORE_PROVIDER=qdrant
      - QDRANT_URL=http://qdrant:6333
    depends_on:
      - qdrant

  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
    volumes:
      - qdrant_data:/qdrant/storage

volumes:
  qdrant_data:
```

--------------------------------

### Install vips and Redis

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Installs the libvips image processing library and Redis in-memory data store.

```shell
brew install vips redis
```

--------------------------------

### Start Ollama Server

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Command to start the Ollama local LLM server.

```bash
ollama serve
```

--------------------------------

### Install WSL and Ubuntu

Source: https://github.com/we-promise/sure/wiki/Windows-Dev-Setup-Guide

Installs the Windows Subsystem for Linux and the Ubuntu distribution. This command should be run in PowerShell.

```powershell
wsl --install -d Ubuntu
```

--------------------------------

### Prepare Database (Create and Migrate)

Source: https://github.com/we-promise/sure/blob/main/CLAUDE.md

Creates the database if it doesn't exist and then runs all pending migrations. This is typically used for initial setup.

```bash
bin/rails db:prepare
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md

Run this command to confirm Docker is installed and running correctly on your system.

```bash
# If Docker is setup correctly, this command will succeed
docker run hello-world
```

--------------------------------

### Example: Add MyBank Family Provider

Source: https://github.com/we-promise/sure/blob/main/docs/api/rails_provider_generator.md

This example demonstrates adding a 'MyBank' provider using the `provider:family` generator. It includes fields for API key, base URL, and refresh token, marking sensitive fields as secrets.

```bash
rails g provider:family my_bank \
  api_key:text:secret \
  base_url:string:default=https://api.mybank.com \
  refresh_token:text:secret
```

--------------------------------

### Install or Upgrade Sure Helm Chart

Source: https://github.com/we-promise/sure/blob/main/charts/sure/README.md

Install or upgrade the Sure Helm chart, creating the namespace if it doesn't exist and waiting for resources to become ready.

```sh
helm upgrade --install sure charts/sure -n sure --create-namespace --wait
```

--------------------------------

### Example: Add Plaid Global Provider

Source: https://github.com/we-promise/sure/blob/main/docs/api/rails_provider_generator.md

This example shows how to add a 'Plaid' provider using the `provider:global` generator. It includes fields for client ID, secret, and environment, with sensitive fields marked as secrets and a default environment set.

```bash
rails g provider:global plaid \
  client_id:string:secret \
  secret:string:secret \
  environment:string:default=sandbox
```

--------------------------------

### Install htop and Create Health Check Script

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Installs htop for system monitoring and creates a basic health check script for the application.

```bash
# Install htop for system monitoring
apt install -y htop

# Create a simple health check script
nano /opt/sure/health-check.sh
```

--------------------------------

### Install Ollama on Linux

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Use a curl script to install Ollama on Linux.

```bash
# Linux
curl -fsSL https://ollama.com/install.sh | sh
```

--------------------------------

### Install rbenv and ruby-build

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Installs rbenv for Ruby version management and ruby-build for compiling Ruby.

```shell
brew install rbenv ruby-build
```

--------------------------------

### Start PostgreSQL Service

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Starts the PostgreSQL service to run in the background.

```shell
brew services start postgresql
```

--------------------------------

### Pipelock Extra Configuration Example

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/pipelock.md

Example of how to configure advanced Pipelock settings like session profiling using Helm's `extraConfig`.

```yaml
pipelock:
  extraConfig:
    session_profiling:
      enabled: true
      max_sessions: 1000
```

--------------------------------

### Install Nginx and Certbot

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Installs Nginx web server and Certbot for managing Let's Encrypt SSL certificates.

```bash
# Install Nginx and Certbot
apt install -y nginx certbot python3-certbot-nginx
```

--------------------------------

### Install Sure Chart with Secret and Image Tag

Source: https://github.com/we-promise/sure/blob/main/charts/sure/README.md

Installs the CNPG operator, a Postgres cluster, and Redis. It also creates an app Secret if provided. Recommended to pin an immutable image tag for production stability.

```sh
# Namespace
kubectl create ns sure || true

# Install chart (example: provide SECRET_KEY_BASE and pin an immutable image tag)
helm upgrade --install sure charts/sure \
  -n sure \
  --set image.tag=v1.2.3 \
  --set rails.secret.enabled=true \
  --set rails.secret.values.SECRET_KEY_BASE=$(openssl rand -hex 32)
```

--------------------------------

### Initialize rbenv

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Initializes rbenv in the current shell session. Follow the on-screen instructions to complete setup.

```shell
rbenv init
```

--------------------------------

### Start Sure MCP Stack

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/mcp.md

Launch the Sure MCP stack using Docker Compose with the downloaded configuration. This command starts the necessary services in detached mode.

```bash
docker compose -f compose.ai.yml up -d
```

--------------------------------

### Install libvips for ActiveStorage

Source: https://github.com/we-promise/sure/wiki/Linux-Dev-Setup-Guide

Installs the libvips library, which is a required dependency for ActiveStorage on Linux. This command requires sudo privileges.

```sh
sudo apt install libvips
```

--------------------------------

### Rails Provider Generator: Global Example

Source: https://github.com/we-promise/sure/blob/main/docs/api/rails_provider_generator.md

Example of generating a global provider for 'plaid'. All families will share the same 'client_id' (secret), 'secret' (secret), and 'environment' (defaulting to 'sandbox').

```bash
# Global: All families share the same Plaid credentials
rails g provider:global plaid \
  client_id:string:secret \
  secret:string:secret \
  environment:string:default=sandbox
```

--------------------------------

### Combine Filters with Pagination

Source: https://github.com/we-promise/sure/blob/main/docs/api/categories.md

Example demonstrating how to combine multiple filtering parameters with pagination settings for the categories endpoint.

```http
GET /api/v1/categories?classification=expense&roots_only=true&page=1&per_page=10
```

--------------------------------

### Install CocoaPods Dependencies

Source: https://github.com/we-promise/sure/blob/main/mobile/docs/iOS_BUILD.md

Run this command after initial setup or dependency updates to install native iOS dependencies required by Flutter plugins.

```bash
flutter pub get
cd ios
pod install
cd ..
```

--------------------------------

### Install rbenv and ruby-build

Source: https://github.com/we-promise/sure/wiki/Windows-Dev-Setup-Guide

Clones the rbenv repository and configures the bash environment to initialize rbenv. It also clones the ruby-build plugin for rbenv.

```bash
git clone https://github.com/rbenv/rbenv.git ~/.rbenv
echo 'eval "$(~/.rbenv/bin/rbenv init - bash)"' >> ~/.bashrc
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
```

--------------------------------

### List Merchants Request

Source: https://github.com/we-promise/sure/blob/main/docs/api/merchants.md

Example HTTP GET request to retrieve a list of merchants.

```http
GET /api/v1/merchants
Authorization: Bearer <access_token>
```

--------------------------------

### List Available Ruby Versions with rbenv

Source: https://github.com/we-promise/sure/wiki/Windows-Dev-Setup-Guide

Lists all Ruby versions available for installation via rbenv's ruby-build plugin.

```shell
rbenv install --list
```

--------------------------------

### Create Application Directory and Download Docker Compose

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Creates the application directory and downloads the example Docker Compose configuration file for Sure. This prepares the environment for running Sure with Docker Compose.

```bash
# Create directory for the application
mkdir -p /opt/sure
cd /opt/sure

# Download the Docker Compose configuration
curl -o compose.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.yml
```

--------------------------------

### Install Flutter Dependencies

Source: https://github.com/we-promise/sure/blob/main/mobile/README.md

Installs project dependencies using Flutter. For iOS, it also installs CocoaPods dependencies.

```bash
flutter pub get

# For iOS development, also install CocoaPods dependencies
cd ios
pod install
cd ..
```

--------------------------------

### Download Sample Docker Compose File

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md

Fetch the sample `compose.yml` file from the Sure GitHub repository to your current directory.

```bash
# Download the sample compose.yml file from the GitHub repository
curl -o compose.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.yml
```

--------------------------------

### Install Ollama on macOS

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Use Homebrew to install Ollama on macOS.

```bash
# macOS
brew install ollama
```

--------------------------------

### Local Development Bind (IPv6 Dual-Stack)

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md

Run the local development server with BINDING=:: for IPv6 dual-stack support.

```bash
BINDING=::       bin/dev  # IPv6 dual-stack
```

--------------------------------

### Instantiate and Test Your Provider in Rails Console

Source: https://github.com/we-promise/sure/blob/main/docs/llm-guides/adding-a-securities-provider.md

Demonstrates how to create an instance of your custom provider and perform search and price fetching operations.

```ruby
# In rails console:
provider = Provider::YourProvider.new("your_api_key")

# Search
response = provider.search_securities("AAPL")
response.success? # => true
response.data     # => [SecurityConcept::Security(...), ...]

# Price
response = provider.fetch_security_price(symbol: "AAPL", exchange_operating_mic: "XNAS", date: Date.current)
response.data.price    # => 150.25
response.data.currency # => "USD"

# Historical prices
response = provider.fetch_security_prices(symbol: "AAPL", exchange_operating_mic: "XNAS", start_date: 30.days.ago.to_date, end_date: Date.current)
response.data.size # => ~30
```

--------------------------------

### Implement Provider Building with Error Handling

Source: https://github.com/we-promise/sure/blob/main/docs/api/rails_provider_generator.md

This method demonstrates how to safely build a provider instance, including checks for family and item presence, credential configuration, and handling specific configuration errors.

```ruby
def self.build_provider(family:)
  return nil unless family.present?

  item = family.my_bank_items.where.not(api_key: nil).first
  return nil unless item&.credentials_configured?

  begin
    Provider::MyBank.new(item.api_key)
  rescue Provider::MyBank::ConfigurationError => e
    Rails.logger.error("MyBank provider configuration error: #{e.message}")
    nil
  end
end
```

--------------------------------

### Install Homebrew

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Installs Homebrew package manager on macOS if it's not already present.

```shell
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

--------------------------------

### Custom Assistant Implementation

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Example of how to create a custom assistant by inheriting from Assistant::Base and implementing the respond_to method. This allows for custom logic in assistant responses.

```ruby
class Assistant::MyCustom < Assistant::Base
  def respond_to(message)
    # Your custom logic here
    assistant_message = AssistantMessage.new(chat: chat, content: "Response")
    assistant_message.save!
  end
end
```

--------------------------------

### Start Redis Service

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Starts the Redis service to run in the background. Required for Sidekiq to boot.

```shell
brew services start redis
```

--------------------------------

### Configure and Enable Nginx Site

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Enables the custom Nginx site configuration, removes the default configuration, tests the Nginx configuration, and starts the Nginx service.

```bash
# Enable the site
ln -s /etc/nginx/sites-available/sure /etc/nginx/sites-enabled/
rm /etc/nginx/sites-enabled/default

# Test Nginx configuration
nginx -t

# Start Nginx
systemctl enable nginx
systemctl start nginx
```

--------------------------------

### Start Redis Manually

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Starts a Redis server instance manually in a separate terminal if not running as a service.

```shell
redis-server --port 6379
```

--------------------------------

### Check Application Logs

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Use this command to stream application logs and identify startup errors.

```bash
# Check logs for errors
docker compose logs -f
```

--------------------------------

### Shell Redis URL Example

Source: https://github.com/we-promise/sure/blob/main/charts/sure/README.md

Example of how to express the REDIS_URL in shell contexts when using the OT redis-operator.

```shell
redis://default:$(REDIS_PASSWORD)@<name>-redis-master.<namespace>.svc.cluster.local:6379/0
```

--------------------------------

### Install Ruby Build Dependencies

Source: https://github.com/we-promise/sure/wiki/Linux-Dev-Setup-Guide

Installs essential dependencies required for building Ruby and other development tools on Ubuntu.

```sh
sudo apt-get install git-core zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev
```

--------------------------------

### Deploy Sure Application with Docker Compose

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Navigate to the application directory, pull the latest Docker images, and start the application in detached mode. Use 'docker compose ps' to check status and 'docker compose logs' to view logs.

```bash
# Navigate to the application directory
cd /opt/sure

# Pull the latest Docker images
docker compose pull

# Start the application
docker compose up -d

# Check if everything is running
docker compose ps

# View logs to ensure everything started correctly
docker compose logs -f
```

--------------------------------

### Subcategory Object Example

Source: https://github.com/we-promise/sure/blob/main/docs/api/categories.md

An example of a subcategory response, showing the 'parent' object with the ID and name of its parent category.

```json
{
  "id": "uuid",
  "name": "Restaurants",
  "classification": "expense",
  "color": "#f97316",
  "icon": "utensils",
  "parent": {
    "id": "uuid",
    "name": "Food & Drink"
  },
  "subcategories_count": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

--------------------------------

### Docker Compose for Sure and Ollama

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Example Docker Compose configuration to run Sure and Ollama services. Includes optional GPU configuration for Ollama.

```yaml
services:
  sure:
    environment:
      - OPENAI_ACCESS_TOKEN=ollama-local
      - OPENAI_URI_BASE=http://ollama:11434/v1
      - OPENAI_MODEL=llama3.1:13b
      - AI_DEBUG_MODE=true # Optional: enable debug logging in the AI chat
    depends_on:
      - ollama
  
  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    # Uncomment if you have an NVIDIA GPU
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: 1
    #           capabilities: [gpu]

volumes:
  ollama_data:
```

--------------------------------

### List All Database Providers

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/oidc.md

Run this command to display all SSO providers currently stored in the database.

```bash
rails sso_providers:list
```

--------------------------------

### Configure Claude Desktop MCP Server

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/mcp.md

Set up Claude Desktop to connect to Sure's MCP server. Ensure the endpoint and authorization header are correctly configured.

```text
http://your-server:8889
Authorization: Bearer your-secret-token
```

--------------------------------

### Run Documentation Specs

Source: https://github.com/we-promise/sure/blob/main/docs/api/users.md

Run just the documentation specs using this command.

```sh
bundle exec rspec spec/requests/api/v1/users_spec.rb
```

--------------------------------

### Rails Provider Generator: Per-Family Example

Source: https://github.com/we-promise/sure/blob/main/docs/api/rails_provider_generator.md

Example of generating a per-family provider for 'lunchflow'. Each family will have its own 'api_key' (secret) and 'base_url'.

```bash
# Per-family: Each family has their own Lunchflow API key
rails g provider:family lunchflow api_key:text:secret base_url:string
```

--------------------------------

### Install Specific Ruby Version

Source: https://github.com/we-promise/sure/wiki/Mac-Dev-Setup-Guide

Installs a specific Ruby version managed by rbenv. Replace `<required-ruby-version>` with the actual version number.

```shell
rbenv install <required-ruby-version>
```

--------------------------------

### Start Rails Server Only

Source: https://github.com/we-promise/sure/blob/main/CLAUDE.md

Starts only the Rails web server. Useful if you need to work solely on the Rails application without other services.

```bash
bin/rails server
```

--------------------------------

### Local Development Bind (LAN Access)

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md

Run the local development server with BINDING=0.0.0.0 to make it reachable from other devices on the same LAN.

```bash
BINDING=0.0.0.0 bin/dev   # reachable from LAN
```

--------------------------------

### Download and Run AI Compose Files

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md

Download the main and AI-specific compose files, along with the Pipelock configuration. Then, run Sure with Pipelock enabled, optionally including a local LLM like Ollama.

```bash
# Download both compose files
curl -o compose.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.yml
curl -o compose.ai.yml https://raw.githubusercontent.com/we-promise/sure/main/compose.example.ai.yml
curl -o pipelock.example.yaml https://raw.githubusercontent.com/we-promise/sure/main/pipelock.example.yaml

# Run with Pipelock (no local LLM)
docker compose -f compose.ai.yml up -d

# Run with Pipelock + Ollama
docker compose -f compose.ai.yml --profile ai up -d
```

--------------------------------

### Install CocoaPods and Build iOS Release

Source: https://github.com/we-promise/sure/blob/main/mobile/README.md

Before building for iOS, ensure CocoaPods dependencies are installed. This command builds the release version of the iOS app.

```bash
cd ios && pod install && cd ..

flutter build ios --release
```

--------------------------------

### Rails Provider Generators: Quick Start

Source: https://github.com/we-promise/sure/blob/main/docs/api/rails_provider_generator.md

Use these commands to quickly generate per-family or global provider configurations. Per-family providers manage separate credentials for each family, while global providers use a single set of credentials for the entire application.

```bash
# Per-Family Provider (each family has separate credentials)
rails g provider:family <PROVIDER_NAME> field:type[:secret] ...

# Global Provider (all families share site-wide credentials)
rails g provider:global <PROVIDER_NAME> field:type[:secret] ...
```

--------------------------------

### Install Ruby Dependencies on Ubuntu

Source: https://github.com/we-promise/sure/wiki/Windows-Dev-Setup-Guide

Updates the package repository and installs essential dependencies required for building and managing Ruby versions using rbenv.

```bash
sudo apt-get update

sudo apt-get install git-core zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2-dev libxslt1-dev libcurl4-openssl-dev software-properties-common libffi-dev
```

--------------------------------

### Run the App on Web (Development)

Source: https://github.com/we-promise/sure/blob/main/mobile/README.md

Launches the Sure Mobile application in a web browser for development purposes.

```bash
# For web (development only)
flutter run -d chrome
```

--------------------------------

### Run Sure App with Docker Compose

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/docker.md

Use this command to start the Sure application. It will pull the official Docker image and display logs in your terminal.

```bash
docker compose up
```

--------------------------------

### Merchant Import CSV Format Example

Source: https://github.com/we-promise/sure/blob/main/docs/api/merchants.md

Example CSV content for importing merchants. Includes columns for name, color, and website URL. Existing merchants with the same name are skipped.

```csv
name,color,website_url
Coffee Shop,#e99537,https://coffeeshop.com
Pizza Palace,#4da568,https://pizzapalace.com
Bookstore,,

```

--------------------------------

### Check Web Pod Logs

Source: https://github.com/we-promise/sure/blob/main/charts/sure/templates/NOTES.txt

Retrieve logs from the Sure web deployment to troubleshoot issues.

```bash
kubectl logs deploy/{{ include "sure.fullname" . }}-web -n {{ .Release.Namespace }}
```

--------------------------------

### Create Environment File

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Creates a .env file for storing environment variables. Replace placeholder values with your actual configuration.

```bash
# Create environment file
nano .env
```

--------------------------------

### Example Kubernetes Secret for Sure Chart

Source: https://github.com/we-promise/sure/blob/main/charts/sure/README.md

This example Secret manifest defines the expected keys for Rails, Active Record Encryption, and Redis. It uses placeholder values and emphasizes using external secret management for production.

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: sure-secrets
type: Opaque
stringData:
  # Rails secrets
  SECRET_KEY_BASE: "__SET_SECRET__"

  # Active Record Encryption keys (optional but recommended when using encryption features)
  ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY: "__SET_SECRET__"
  ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY: "__SET_SECRET__"
  ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT: "__SET_SECRET__"

  # Redis password used by operator-managed or simple Redis
  redis-password: "__SET_SECRET__"

  # Optional: CNPG bootstrap user/password if you are not letting the chart generate them
  # username: "sure"
  # password: "__SET_SECRET__"

```

--------------------------------

### Call a Tool with Arguments

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/mcp.md

Execute a specific tool, such as 'get_transactions', by providing its name and arguments in the 'tools/call' request. This example shows how to fetch transactions for a given date range.

```bash
curl -X POST https://your-sure-instance/mcp \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_transactions",
      "arguments": {
        "start_date": "2024-01-01",
        "end_date": "2024-01-31"
      }
    }
  }'
```

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{"id":"...","amount":-45.99,"date":"2024-01-15","name":"Coffee Shop"}]"
      }
    ]
  }
}
```

--------------------------------

### API V1 Widgets RSpec Example

Source: https://github.com/we-promise/sure/blob/main/CLAUDE.md

This RSpec example demonstrates how to define an API endpoint for listing widgets using rswag. It includes tags, security definitions, response schemas, and the `run_test!` helper for generating OpenAPI documentation.

```ruby
require 'swagger_helper'

RSpec.describe 'API V1 Widgets', type: :request do
  path '/api/v1/widgets' do
    get 'List widgets' do
      tags 'Widgets'
      security [ { apiKeyAuth: [] } ]
      produces 'application/json'
      
      response '200', 'widgets listed' do
        schema '$ref' => '#/components/schemas/WidgetCollection'
        run_test!
      end
    end
  end
end
```

--------------------------------

### Example Future WebSocket Assistant Implementation

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

A placeholder for a future Assistant implementation that would use WebSocket connections for bidirectional communication and tool handling.

```ruby
class Assistant::WebSocket < Assistant::Base
  def respond_to(message)
    # Connect via WebSocket
    # Stream bidirectional communication
    # Handle tool calls via MCP
  end
end
```

--------------------------------

### Qdrant Configuration for Self-Hosted Document Search

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Set environment variables to configure Qdrant as the vector store provider, including the Qdrant URL and an optional API key.

```bash
VECTOR_STORE_PROVIDER=qdrant
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your-api-key
```

--------------------------------

### Get All Expense Categories

Source: https://github.com/we-promise/sure/blob/main/docs/api/categories.md

Retrieve all categories that are classified as expenses.

```http
GET /api/v1/categories?classification=expense
```

--------------------------------

### HA Setup with Topology Spreading for Web Deployments

Source: https://github.com/we-promise/sure/blob/main/charts/sure/README.md

Configure HA for web deployments with `replicas: 3`, a rolling update strategy of `maxUnavailable: 1` and `maxSurge: 0`, and specific topology spread constraints. This ensures high availability and proper pod distribution across nodes.

```yaml
web:
  replicas: 3
  strategy:
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 0
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: kubernetes.io/hostname
      whenUnsatisfiable: DoNotSchedule
      labelSelector:
        matchLabels:
          app.kubernetes.io/name: sure
          app.kubernetes.io/component: web
```

--------------------------------

### Create Sure Application Backup Script

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Create and configure a bash script to perform daily backups of the Sure application's database and storage. The script creates a backup directory, dumps the database, archives application data, and cleans up old backups.

```bash
# Create backup script
nano /opt/sure/backup.sh
```

```bash
#!/bin/bash
BACKUP_DIR="/opt/sure/backups"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p $BACKUP_DIR

# Backup database
docker compose exec -T db pg_dump -U sure_user sure_production > $BACKUP_DIR/db_backup_$DATE.sql

# Backup application data
docker compose exec -T web tar -czf - /rails/storage > $BACKUP_DIR/storage_backup_$DATE.tar.gz

# Keep only last 7 days of backups
find $BACKUP_DIR -name "*.sql" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

echo "Backup completed: $DATE"
```

```bash
# Make backup script executable
chmod +x /opt/sure/backup.sh
```

--------------------------------

### Get Only Root Categories

Source: https://github.com/we-promise/sure/blob/main/docs/api/categories.md

Retrieve only top-level categories, excluding any subcategories.

```http
GET /api/v1/categories?roots_only=true
```

--------------------------------

### Enable and Test Provider Integration

Source: https://github.com/we-promise/sure/blob/main/docs/llm-guides/adding-a-securities-provider.md

Shows how to enable your provider and use the system's multi-provider search, security resolution, and price import functionalities.

```ruby
# Enable the provider
Setting.securities_providers = "your_provider"

# Search via the app's multi-provider system
results = Security.search_provider("AAPL")
results.map { |s| [s.ticker, s.price_provider] }
# => [["AAPL", "your_provider"]]

# Create a security with your provider
security = Security::Resolver.new("AAPL", exchange_operating_mic: "XNAS", price_provider: "your_provider").resolve
security.price_provider # => "your_provider"

# Import prices
security.import_provider_prices(start_date: 30.days.ago.to_date, end_date: Date.current)
security.prices.count
```

--------------------------------

### List SSL Certificates

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/hetzner.md

Display information about currently installed SSL certificates.

```bash
# Check certificate status
certbot certificates
```

--------------------------------

### MCP Example: List Tools

Source: https://github.com/we-promise/sure/blob/main/docs/hosting/ai.md

Use curl to send a JSON-RPC 2.0 request to the MCP endpoint to list available tools. Requires Authorization header with the MCP API token.

```bash
curl -X POST https://your-sure-instance/mcp \
  -H "Authorization: Bearer $MCP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

--------------------------------

### GET /api/v1/chats

Source: https://github.com/we-promise/sure/blob/main/docs/api/chats.md

Lists chats for the authenticated user, including pagination metadata.

```APIDOC
## GET /api/v1/chats

### Description
List chats for the authenticated user with pagination metadata.

### Method
GET

### Endpoint
/api/v1/chats

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number for pagination.
- **per_page** (integer) - Optional - The number of items per page.

### Response
#### Success Response (200)
- **chats** (array) - A list of chat objects.
- **pagination** (object) - Pagination metadata.

Refer to the generated `openapi.yaml` for detailed schemas.
```