Install from source#

This page installs Chatvia from its Git repository on your own computer. The app runs with your own PHP and Node.js, and PostgreSQL and Redis run on your machine too. It is the way to go when you want to read or change the code, contribute, or run Chatvia without containers.

Requirements#

Install these on your computer before you start.

Software#

brew install php composer node@22 git

pecl install redis

sudo add-apt-repository ppa:ondrej/php
sudo apt update
sudo apt install git unzip php8.5-cli php8.5-pgsql php8.5-redis php8.5-intl \
  php8.5-mbstring php8.5-curl php8.5-zip php8.5-gd php8.5-xml

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash -
sudo apt install nodejs

curl -sS https://getcomposer.org/installer | php
sudo mv composer.phar /usr/local/bin/composer

Services#

For now, Chatvia needs Redis and Laravel Horizon, also on your own computer. See Redis and Horizon are required. Step 2 installs the services.

Programs for some file types#

All of them are optional. Without one, Chatvia does the work itself, or turns away only the files it cannot read.

# macOS
brew install poppler pandoc catdoc ffmpeg weasyprint

# Ubuntu and Debian
sudo apt install poppler-utils pandoc catdoc ffmpeg weasyprint

PowerPoint (.pptx) and Excel (.xlsx) files need no extra program. If a program is not on the PATH of the web server or the queue workers (for example Homebrew's /opt/homebrew/bin on a Mac), enter its full path in the admin panel, under Settings → Platform → Programs.

An AI provider#

1. Get the code#

git clone https://github.com/chatvia/chatvia.git
cd chatvia

Every command below runs in this folder.

2. Set up PostgreSQL and Redis#

1. Install PostgreSQL with pgvector, Redis and Mailpit, and start them:

   bash

   # macOS
   brew install postgresql@18 pgvector redis mailpit
   brew services start postgresql@18
   brew services start redis
   brew services start mailpit
   
   # Ubuntu and Debian
   sudo apt install postgresql-18 postgresql-18-pgvector redis-server

   On Ubuntu, install Mailpit with the steps on its website, or skip it and set MAIL_MAILER=log in step 4.

2. Create a role and the five databases: chatvia for the app, testing for the tests, analytics for the numbers behind the charts and reports, and pulse and spectra, where Pulse (/pulse) and Spectra (/spectra) keep their data. The first migration runs CREATE EXTENSION, so the role needs the right to do that. On your own computer, a superuser is simplest. Open psql (on macOS with psql postgres, on Ubuntu with sudo -u postgres psql) and run:

   sql

   CREATE ROLE chatvia LOGIN SUPERUSER PASSWORD 'password';
   CREATE DATABASE chatvia OWNER chatvia;
   CREATE DATABASE testing OWNER chatvia;
   CREATE DATABASE analytics OWNER chatvia;
   CREATE DATABASE pulse OWNER chatvia;
   CREATE DATABASE spectra OWNER chatvia;

3. Optional: install pg_textsearch from its releases page, load it in postgresql.conf and restart PostgreSQL:

   ini

   shared_preload_libraries = 'pg_textsearch'

   Without it, keyword search uses PostgreSQL's built-in full-text search (see The database).

4. Optional: install pg_partman (on Ubuntu, the postgresql-18-partman package). It splits the analytics event log into one table per month, so old months are removed in one step. Without it, the log stays one table and old rows are deleted in batches.

PostgreSQL listens on 127.0.0.1:5432, Redis on 127.0.0.1:6379, and Mailpit on 127.0.0.1:1025, with its inbox at http://localhost:8025. These are the addresses .env.example expects.

docker compose up -d
docker compose ps

3. Install the packages#

composer install
npm ci

composer install stops with a clear message when a PHP extension is missing. Install it and run the command again.

4. Create the .env file#

cp .env.example .env
php artisan key:generate

.env.example has a short comment on every setting, and its defaults already match the services from step 2:

APP_URL=http://localhost:8000

DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=chatvia
DB_USERNAME=chatvia
DB_PASSWORD=password

REDIS_HOST=127.0.0.1
REDIS_PORT=6379
QUEUE_CONNECTION=redis

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025

Two secrets have no value yet. Fill them in with random strings:

# Signs the calls to the built-in tools (charts, forms, weather, ...). They stop working while it is empty.
BUILTIN_MCP_SECRET=
# Signs the live updates from Reverb.
REVERB_APP_SECRET=

openssl rand -hex 32

API keys for outside services are not in .env. You enter them in the admin panel in step 8, where they are stored encrypted.

5. Create the database tables#

php artisan chatvia:deploy:migrate
php artisan storage:link

chatvia:deploy:migrate checks that the analytics, Pulse and Spectra databases are there, and creates any that are missing. Then it creates the tables, checks the embedding settings and adds the built-in tools. On a new install the built-in tools only show a warning: they need the API key you enter in step 8. The first migration installs the PostgreSQL extensions. If it fails with extension "vector" is not available, pgvector is not installed in this PostgreSQL (step 2), or DB_HOST and DB_PORT point at another server.

The AI models that agents can pick from are added in the admin panel's setup, in step 8.

6. Create your admin account#

php artisan chatvia:admin:create-user [email protected] "Your Name"

The command asks for a password, so it does not end up in your shell history. The account is an admin with its own workspace and team.

7. Start the app#

composer dev

This starts four processes in one terminal:

Two more processes need their own terminal:

# Reads documents, sends channel replies and exports: jobs on every queue, not only "default".
php artisan horizon

# Live updates in the browser, such as the progress of a document being read.
php artisan reverb:start

And two more when you need them, each in its own terminal too:

# Scheduled cleanup, statistics and backups.
php artisan schedule:work

# The CPU, memory and disk on the Servers card at /pulse.
php artisan pulse:check

If you use Herd or Valet, they serve the app at http://chatvia.test instead of php artisan serve. Set APP_URL to that address.

8. Add your API keys#

1. Open the admin panel at http://localhost:8000/admin and sign in with the account from step 6.

2. The admin panel opens with the setup of a new install. Choose your AI provider and enter its API key, pick the chat and embedding models, and click Finish setup. You can change it all later under Settings → AI providers and Settings → AI models.

3. Finishing the setup adds Chatvia's built-in tools (charts, forms, weather, currency, web search) to the tool catalog. If you skipped the setup, add them after you entered the key, as they use your embedding provider:

   bash

   php artisan chatvia:mcp:sync-builtin

Settings can also be read and changed from the command line: php artisan chatvia:settings:list lists them and php artisan chatvia:settings:set sets one.

Check that it works#

1. Open http://localhost:8000, sign in, and create an agent from Dashboard → Agents → Create agent.
2. Add a source, for example a short PDF or a text snippet. Its status moves from Pending to Processing to Ingested.
3. Ask a question in the agent's Playground. The answer streams in. Open the chat in Chatlog to see the parts of your sources it used.
4. Open Mailpit at http://localhost:8025 to see the e-mails Chatvia sent.

Update#

git pull
composer install
npm ci
php artisan chatvia:deploy:migrate

Then restart composer dev, Horizon, Reverb and pulse:check (when it runs), so they run the new code.

Run the tests#

The tests use the testing database from step 2:

composer test

Troubleshooting#