Run Bosca Locally

Start Bosca on your computer with Docker Compose to explore Studio, manage content, run jobs and pipelines, host Git repositories, and collect analytics.

The root stack includes the Primary GraphQL Server, a Job Runner, Studio, Git and Artifacts servers, BML message rendering, image processing, PostgreSQL with pgvector, NATS, Redis, Meilisearch, S3 storage, and a Trino and Iceberg warehouse.

This setup uses local HTTP and default credentials. Published ports bind to loopback. For deployment on a public host, configure your own ingress, HTTPS, credentials, and storage. Or use the `bosca swarm` commands.

Requirements

• Docker Engine or Docker Desktop with Docker Compose v2.
• A checkout of the Bosca repository.
• Memory for the applications and databases; Trino alone uses a 2 GiB heap.
• Available local ports 3000, 8091, and 8084.

The application images use linux/amd64. On an ARM machine, Docker Desktop needs amd64 emulation enabled.

Start Bosca

From the repository root:

No configuration file or separate pull command is required. Compose downloads missing images and starts the services. Keep this terminal open while using Bosca; press Ctrl+C to stop the containers. To run in the background and wait for readiness:

Compose waits for dependencies and application readiness. The one-time storage-init container creates the storage and warehouse buckets and exits successfully. The API applies database migrations and installs initial platform data. The runner processes background jobs and analytics events.

Sign In to Studio

Open http://bosca.localhost:3000 and sign in with username admin and password password. You can override the initial password with INIT_ADMIN_PASSWORD.

The installer creates this account on the first start. Changing INIT_ADMIN_PASSWORD later does not reset an existing account's password.

Use bosca.localhost consistently. Browsers resolve the name to loopback, while containers resolve it to the stack's web proxy. This lets image processing fetch the same signed content URLs used by the browser. If another client does not resolve it, add 127.0.0.1 bosca.localhost to that machine's hosts file or use its explicit DNS override.

Try the Instance

Create a collection, upload a file, or use the editor to create a document in Studio. Git clone URLs point to the dedicated Git server. The Artifacts server is available for publishing and retrieving artifacts.

Studio's API requests, GraphQL subscriptions, and collaborative editing use the same web origin. Databases, object storage, queues, search, image processing, and the message rendering API are internal to the Compose network.

Optional Configuration and Integrations

To override the defaults, copy .env.example to .env and edit the settings you need. BOSCA_IMAGE_REGISTRY selects a registry mirror, and BOSCA_VERSION selects the application tag. The image processor has a separate tag, BOSCA_IMAGEPROCESSOR_VERSION. The default tags are pinned in the root Compose file. Public images come from ghcr.io/bosca-io. Recreate the containers after changing settings.

To refresh the repository's default Bosca image versions, run the following with curl and jq installed. The script selects the newest stable release available for all application images and updates the image processor separately. It checks the published manifests before editing the Compose file and .env.example. Existing .env overrides still take precedence. Add --dry-run to preview changes.

Content storage, ordinary search, job processing, Git hosting, and the analytics warehouse use the services in this stack.

• AI: set OPENAI_API_KEY for the agent runtime. Configure providers for other model workflows through Studio.
• Google sign-in: set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET with the callback http://bosca.localhost:3000/oauth2/google/callback.
• Email: use SendGrid or Mailgun. Set MAILER_TYPE and MAILER_FROM_EMAIL, then configure the provider's encrypted credentials in Studio.
• Message projects: the BML message server starts with the bundled bosca-messages project. To load projects published to this instance's Artifacts server, set BML_MESSAGE_ARTIFACTS_TOKEN to a token with read access to its bml-message repository.

Semantic embeddings and trained recommendation models require their model services and artifacts. Kubernetes operations require a cluster and controller. Those services are not started by this Compose file.

Continue with the CLI guide for programmatic access, or GraphQL to send your first API request.

Keep or Reset Your Data

Stopping the stack preserves named volumes containing PostgreSQL data, objects, NATS streams, Redis data, search indexes, message caches, and staged analytics. The project name is bosca-local, separate from the development stacks.

To permanently delete this instance's data and start over:

Troubleshooting

Inspect the failing service before retrying:

If pulling an image reports manifest unknown, verify that the selected release contains every image in the stack. If a port is in use, change BOSCA_PORT, BOSCA_GIT_PORT, or BOSCA_ARTIFACTS_PORT in .env and recreate the services with docker compose up -d --wait --wait-timeout 600. Public URLs derive from those settings.

To run the backend from source, follow the local development instructions. The root Compose stack has its own databases and volumes.