Local development

sov start runs the same services your cloud project uses, as Docker containers on your machine. It creates a developer account, an organization and a project, applies sovaria/migrations, loads sovaria/seed.sql, and writes the project URL and keys into .env.local. Nothing leaves your machine except the image download; every email lands in a local inbox.

#Start the stack

1. 1

   Install Docker

   Docker Desktop, or Docker Engine with the Compose v2 plugin. You don't need a Sovaria account for the local stack.

2. 2

   Start it in your project folder

   The first start downloads the images (pinned to your CLI version) and takes a few minutes; later starts take seconds.

   Terminal

   cd my-app
   sov start                          # core services
   sov start --with forge,pulse,console   # plus functions, realtime and the local console

3. 3

   Use the URL and keys

   sov status prints them; .env.local already has them for your framework (SOVARIA_URL, VITE_SOVARIA_URL, NEXT_PUBLIC_SOVARIA_URL and the anon key).

   Terminal

   sov status

#Well-known local keys

The local stack always uses the same two keys, so tests and example code can hard-code them. They are public and they only work against a local stack: the cloud refuses them, and the local gateway answers only requests addressed to localhost.

#Point your app at the local stack

import { createClient } from '@sovaria/sdk'

const sov = createClient(import.meta.env.VITE_SOVARIA_URL, import.meta.env.VITE_SOVARIA_ANON_KEY)
// local: http://localhost:54321 + svr_local_anon_…   cloud: https://<ref>.sovarias.in + your anon key

#Use the CLI against it

sov start saves a CLI profile called local with a signed-in developer session. Add --profile local to any command; sov simulate local uses it by default and sov fn serve reads .env.local, so functions you run locally call the local stack.

sov db sql --profile local "select count(*) from todos"
sov db migrations new add_notes && sov db migrations push --profile local
sov db reset --local               # drop every table, re-apply migrations and seed
sov fn serve functions/            # SOVARIA_URL and keys come from .env.local
sov simulate local                 # full access simulation against the local stack

#Data: keep, reset or start from production's shape

• sov stop stops the containers and keeps the database, files and logs; sov stop --reset deletes them.
• sov db reset --local empties only the database, then applies your migrations and seed again.
• sov start --from-snapshot snapshot.json recreates the tables, row-level security, policies, SQL functions and sample rows of a cloud project from a simulation snapshot (sov simulate snapshot --rows). No credentials or app users are copied.

#How the local stack differs from the cloud

#Settings

#In CI

- run: pipx install sovaria-cli
- run: sov start --no-env-file
- run: npm test
  env:
    SOVARIA_URL: http://localhost:54321
    SOVARIA_ANON_KEY: svr_local_anon_5a0f1c8e2b7d4e6f9a3c1b5d7e9f0a2c
- run: sov stop --reset --yes
  if: always()