OneGlanse

https://docs.oneglanse.com
Admin
OneGlanse is an open-source GEO and AI visibility tracking platform that monitors how brands appear...
Tokens:10,465
Snippets:118
Trust Score:5.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### Start the local stack

Source: https://docs.oneglanse.com/local-setup

Start the local development stack with `pnpm local`. This command starts Postgres, ClickHouse, and Redis, runs migrations, and bootstraps the browser runtime. The app will be available at http://localhost:3000.

```bash
pnpm local

```

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

### Clone repo and run setup script locally

Source: https://docs.oneglanse.com/self-hosted-setup

Clone the OneGlanse repository and run the setup script locally instead of using the remote script. The script is interactive and asks for your domain, LLM key, and proxy URL.

```bash
git clone https://github.com/aryamantodkar/oneglanse /tmp/oneglanse
bash /tmp/oneglanse/scripts/setup-vps.sh

```

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

### Install dependencies on Ubuntu VPS

Source: https://docs.oneglanse.com/self-hosted-setup

Commands to install Docker, Node.js 20, git, nginx, and certbot on a fresh Ubuntu VPS. Run as a non-root sudo user.

```bash
sudo apt-get update

# Docker
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

# Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# git
sudo apt-get install -y git

# nginx + certbot
sudo apt install -y nginx certbot python3-certbot-nginx
```

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

### DNS A record example

Source: https://docs.oneglanse.com/self-hosted-setup

Example DNS A record pointing a subdomain to the VPS IP. Required before continuing with nginx and certbot setup.

```text
A  app.yourdomain.com  →  YOUR_VPS_IP
```

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

### Run interactive VPS setup script

Source: https://docs.oneglanse.com/self-hosted-setup

Run the interactive setup script on a VPS as a non-root user with sudo access. The script handles dependencies, repo clone, .env config, Docker image pull, nginx, SSL, and firewall. It will stop if run as root.

```bash
# On your VPS (as a non-root user with sudo privileges):
bash <(curl -fsSL https://raw.githubusercontent.com/aryamantodkar/oneglanse/main/scripts/setup-vps.sh)

```

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

### Install pnpm globally

Source: https://docs.oneglanse.com/local-setup

Install pnpm globally if it is not already available. This is required for the local setup commands.

```bash
npm install -g pnpm@latest

```

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

### Create non-root sudo user for VPS setup

Source: https://docs.oneglanse.com/self-hosted-setup

Create a non-root sudo user named 'deploy' on a freshly reinstalled VPS that only has root, optionally copy the root SSH key, and reconnect as the new user before running the setup script.

```bash
# On the VPS as root, once:
adduser deploy
usermod -aG sudo deploy

# Optional: copy your existing root SSH key access to the new user
install -d -m 700 -o deploy -g deploy /home/deploy/.ssh
cp -a /root/.ssh/authorized_keys /home/deploy/.ssh/authorized_keys
chown deploy:deploy /home/deploy/.ssh/authorized_keys
chmod 600 /home/deploy/.ssh/authorized_keys

# Then reconnect as the new user:
ssh deploy@YOUR_VPS_IP

```

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

### Start the stack with bootstrap script

Source: https://docs.oneglanse.com/self-hosted-setup

Runs the bootstrap script to pull Docker images and start the web app, agent worker, Postgres, ClickHouse, and Redis. On a fresh server, this can take several minutes.

```bash
node scripts/run-compose.mjs bootstrap

```

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

### Clone and configure OneGlanse repository

Source: https://docs.oneglanse.com/self-hosted-setup

Clones the OneGlanse repository to the home directory, changes into the project directory, and copies the example environment file to .env.

```bash
git clone https://github.com/aryamantodkar/oneglanse /home/$USER/oneglanse
cd /home/$USER/oneglanse
cp .env.example .env

```

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

### Allow OpenSSH and Nginx Full via UFW

Source: https://docs.oneglanse.com/self-hosted-setup

Enables UFW and allows only OpenSSH and Nginx Full ports. This is the base firewall configuration for the self-hosted setup.

```bash
sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable
```

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

### Obtain SSL certificate with Certbot

Source: https://docs.oneglanse.com/self-hosted-setup

Runs Certbot with the nginx plugin to automatically obtain and install an SSL certificate for the specified domain. Certbot will update the nginx config to redirect HTTP to HTTPS and set up auto-renewal via a systemd timer.

```bash
sudo certbot --nginx -d app.yourdomain.com

```

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

### Create nginx site config file

Source: https://docs.oneglanse.com/self-hosted-setup

Opens the nginx site configuration file for OneGlanse in the nano editor. This is the first step in setting up the reverse proxy.

```bash
sudo nano /etc/nginx/sites-available/oneglanse

```

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

### Enable nginx site and reload

Source: https://docs.oneglanse.com/self-hosted-setup

Creates a symlink to enable the OneGlanse site, removes the default site, tests the nginx configuration, and reloads nginx to apply changes.

```bash
sudo ln -s /etc/nginx/sites-available/oneglanse /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl reload nginx

```

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

### Run provider auth flow

Source: https://docs.oneglanse.com/self-hosted-setup

Opens the provider authentication flow and signs in to each provider. At the end, you will be asked whether to upload the sessions to the VPS; answer 'y' to transfer them.

```bash
pnpm auth

```

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

### Useful Commands

Source: https://docs.oneglanse.com/api-reference

Lists the primary pnpm commands for local development, authentication, self-hosting, and maintenance tasks.

```bash
pnpm local                   # Start full local stack from local source and refresh Docker service/base images when available
pnpm auth                    # Capture provider sessions locally; prompts to upload to VPS at the end
pnpm upload:vps              # Re-upload existing local sessions to VPS without re-running the auth flow
pnpm self-host               # Pull latest published images and start the self-hosted stack; auto-builds locally if your architecture is not published yet
pnpm self-host:build         # Build from source and start the self-hosted stack
pnpm lint                    # Lint Web, Landing, and Agent tests
pnpm test                    # Run automated regression tests
pnpm typecheck               # Typecheck the monorepo
pnpm build                   # Build all packages
```

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

### Check disk usage and Docker system disk usage

Source: https://docs.oneglanse.com/self-hosted-setup

Use these commands to check disk usage when the VPS runs out of disk space, as ClickHouse data grows over time. The first command shows overall disk usage, and the second shows Docker's disk usage.

```bash
df -h
```

```bash
docker system df
```

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

### Verify running containers with docker ps

Source: https://docs.oneglanse.com/self-hosted-setup

Lists running Docker containers to verify that web, agent-worker, postgres, clickhouse, and redis are up.

```bash
docker ps

```

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

### Check migration logs and re-run migrations

Source: https://docs.oneglanse.com/troubleshooting

Check migration logs with `docker logs oneglanse-migrate` and re-run migrations with `pnpm db:migrate` if the migrate container exits with an error.

```bash
# Check migration logs
docker logs oneglanse-migrate

# Re-run migrations manually
pnpm db:migrate

```

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

### Minimum required .env configuration

Source: https://docs.oneglanse.com/self-hosted-setup

Shows the minimum required environment variables: APP_URL, API_BASE_URL, an LLM API key (OpenAI or Anthropic), the Thordata proxy URL, and an auth upload token. If BETTER_AUTH_SECRET or INTERNAL_CRON_SECRET are unset, the bootstrap script generates them automatically.

```bash
# Your public URL
APP_URL=https://app.yourdomain.com
API_BASE_URL=https://app.yourdomain.com

# LLM key for response analysis — pick one:
OPENAI_API_KEY=sk-...
# or:
# ANTHROPIC_API_KEY=sk-ant-...
# ANALYSIS_LLM_PROVIDER=claude

# Residential proxy — required on VPS
THORDATA_PROXY_API_URL=https://your-thordata-endpoint

# Auth upload token — any strong random string
AGENT_AUTH_UPLOAD_TOKEN=replace-with-a-strong-secret

```

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

### Find Python 3 binary for Camoufox

Source: https://docs.oneglanse.com/troubleshooting

Run `which python3` to locate the Python 3 binary path, e.g. `/opt/homebrew/bin/python3`. Use the output to set `CAMOUFOX_PYTHON_BIN` in `.env`.

```bash
which python3
# e.g. /opt/homebrew/bin/python3

```

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

### Set local environment variables for auth upload

Source: https://docs.oneglanse.com/self-hosted-setup

Sets the VPS IP and an authentication upload token in the local .env file. The token must match the one configured on the VPS. This is required for uploading provider auth sessions.

```bash
ONEGLANSE_VPS_IP=YOUR_VPS_IP
AGENT_AUTH_UPLOAD_TOKEN=replace-with-a-strong-secret   # same as on VPS

```

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

### Set Google OAuth credentials in .env

Source: https://docs.oneglanse.com/troubleshooting

Add `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` to `.env` to enable Google sign-in on the OneGlanse web app. These are separate from provider connections.

```bash
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

```

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

### Rerun bootstrap after updating THORDATA_PROXY_API_URL

Source: https://docs.oneglanse.com/self-hosted-setup

Run this after changing THORDATA_PROXY_API_URL in /home/$USER/oneglanse/.env to point to your real residential proxy endpoint. Without the correct proxy endpoint, VPS prompt runs are likely to be blocked, challenged, or less accurate.

```bash
cd /home/$USER/oneglanse
node scripts/run-compose.mjs bootstrap
```

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

### Set analysis LLM key in .env

Source: https://docs.oneglanse.com/local-setup

Configure the analysis LLM provider by setting either the OpenAI or Anthropic API key in the `.env` file. Choose one provider and set the corresponding key and provider variable.

```bash
# Pick one:
OPENAI_API_KEY=sk-...

# or:
ANTHROPIC_API_KEY=sk-ant-...
ANALYSIS_LLM_PROVIDER=claude

```

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

### Edit .env file with nano

Source: https://docs.oneglanse.com/self-hosted-setup

Opens the .env file in the nano text editor to fill in required configuration values.

```bash
nano .env

```

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

### Set CAMOUFOX_PYTHON_BIN in .env

Source: https://docs.oneglanse.com/troubleshooting

Add the `CAMOUFOX_PYTHON_BIN` environment variable to `.env` with the path found from `which python3`. Then restart with `pnpm local`.

```bash
CAMOUFOX_PYTHON_BIN=/opt/homebrew/bin/python3

```

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

### Check ClickHouse container logs

Source: https://docs.oneglanse.com/troubleshooting

Run `docker logs clickhouse_db` to inspect ClickHouse container logs if the dashboard shows no data or a connection error persists.

```bash
docker logs clickhouse_db

```

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

### Check web container logs for 502 Bad Gateway

Source: https://docs.oneglanse.com/self-hosted-setup

Use this command to inspect the logs of the 'oneglanse-web' container when you encounter a 502 Bad Gateway error. The error indicates the web container isn't running yet.

```bash
docker logs oneglanse-web --tail 50
```

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

### Re-upload auth sessions to VPS

Source: https://docs.oneglanse.com/self-hosted-setup

Uploads provider auth sessions to the VPS without going through the sign-in flow again. Use this when a session expires and needs to be refreshed.

```bash
pnpm upload:vps

```

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

### Allow 3333/tcp broadly

Source: https://docs.oneglanse.com/self-hosted-setup

If your local IP changes often, you can allow port 3333 broadly and rely on AGENT_AUTH_UPLOAD_TOKEN for authentication.

```bash
sudo ufw allow 3333/tcp
```

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

### Allow 3333/tcp from a specific IP

Source: https://docs.oneglanse.com/self-hosted-setup

If your local machine has a stable public IP, prefer allowing port 3333 only from that source for the agent upload API.

```bash
sudo ufw allow from YOUR_LOCAL_PUBLIC_IP to any port 3333 proto tcp
```

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

### Pull updates and redeploy without downtime

Source: https://docs.oneglanse.com/self-hosted-setup

Use this to update the self-hosted deployment. It pulls the latest changes and runs the bootstrap script to redeploy without downtime.

```bash
cd /home/$USER/oneglanse
git pull
node scripts/run-compose.mjs bootstrap
```

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

### Renew SSL certificate with certbot

Source: https://docs.oneglanse.com/self-hosted-setup

Run this command to renew the SSL certificate for your domain when you see an SSL certificate failed error. This typically happens when DNS hasn't propagated yet; wait a few minutes and retry.

```bash
sudo certbot --nginx -d app.yourdomain.com
```

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

### nginx server block for OneGlanse

Source: https://docs.oneglanse.com/self-hosted-setup

Defines the nginx server block that proxies requests to the OneGlanse app running on port 3000. Replace 'app.yourdomain.com' with your actual domain. Includes WebSocket upgrade headers and a 120-second read timeout.

```nginx
server {
    listen 80;
    server_name app.yourdomain.com;

    location / {
        proxy_pass         http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection 'upgrade';
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 120s;
    }
}

```

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

### Verify Certbot auto-renewal

Source: https://docs.oneglanse.com/self-hosted-setup

Performs a dry run of the certificate renewal process to verify that auto-renewal is configured correctly.

```bash
sudo certbot renew --dry-run

```
Tokens:
Raw