Quick Start

Choose Docker Compose for a local evaluation or Helm for a Kubernetes deployment. Both paths connect to any backend that exposes a compatible S3 API.

Docker Compose

1. Configure

cp .env.example .env   # fill in your credentials

At minimum, set a production-safe SECRET_KEY and your storage credentials. The included development stack starts MinIO and PostgreSQL for you.

2. Start the stack

docker compose -f docker-compose.dev.yml up -d

3. Open the services

Service	URL
Frontend	http://localhost:3100
Backend API	http://localhost:8200
MinIO Console	http://localhost:9001

Default admin is [email protected] / admin — change this in production.

Kubernetes with Helm

The official chart is published as an OCI artifact. You need Helm 3, an ingress controller, PostgreSQL, and an S3-compatible endpoint. The chart can start embedded MinIO and PostgreSQL for evaluation, but external managed services are recommended for production.

Inspect the available values:

helm show values oci://registry-1.docker.io/bearcomp/s3bear --version 1.0.3 \
	> values.reference.yaml

1. Create production values

Keep this file out of source control when it contains real credentials:

replicaCount: 1

config:
	debug: "false"
	awsRegion: "us-east-1"
	# Backend-reachable S3 API endpoint. Leave empty for AWS S3.
	awsEndpointUrl: "https://objects.example.com"
	# Browser-reachable endpoint used to sign direct multipart uploads.
	presignedUrlBase: "https://objects.example.com"
	multipartPartSizeMb: "10"
	presignedUrlExpiry: "3600"
	allowedOrigins: '["https://s3bear.example.com"]'

secrets:
	secretKey: "REPLACE_WITH_AT_LEAST_32_RANDOM_CHARACTERS"
	defaultAdminEmail: "[email protected]"
	defaultAdminPassword: "REPLACE_WITH_A_STRONG_PASSWORD"
	databaseUrl: "postgresql+asyncpg://USER:[email protected]:5432/s3bear"
	databaseUrlSync: "postgresql://USER:[email protected]:5432/s3bear"
	awsAccessKeyId: "REPLACE_ME"
	awsSecretAccessKey: "REPLACE_ME"
	azureTenantId: ""
	azureClientId: ""
	azureClientSecret: ""
	azureRedirectUri: "https://s3bear.example.com/auth/callback"

ingress:
	enabled: true
	className: nginx
	host: s3bear.example.com
	tls:
		enabled: true
		secretName: s3bear-tls

auditLog:
	enabled: true
	fileEnabled: true
	path: /var/log/s3bear/audit
	retentionDays: 90
	storage:
		enabled: true
		size: 5Gi
		storageClassName: ""
		accessMode: ReadWriteOnce

hpa:
	enabled: true
	minReplicas: 1
	maxReplicas: 5
	cpuUtilization: 70

minio:
	enabled: false

postgresql:
	enabled: false

For AWS S3, leave config.awsEndpointUrl and config.presignedUrlBase empty unless you use a custom public endpoint. For another S3-compatible service, set the endpoint visible to the backend and the endpoint visible to users' browsers. See Storage Providers and CORS Setup.

2. Install

helm install s3bear oci://registry-1.docker.io/bearcomp/s3bear \
	--version 1.0.3 \
	--namespace s3bear \
	--create-namespace \
	--values values.production.yaml

To install from a checked-out chart:

git clone https://github.com/Cenkay1/s3BEAR.git
cd s3BEAR
helm dependency update ./helm/s3bear
helm install s3bear ./helm/s3bear \
	--namespace s3bear --create-namespace \
	--values values.production.yaml

Helm values and environment variables

Helm value	Environment variable	Purpose
`secrets.secretKey`	`SECRET_KEY`	Required JWT signing secret; at least 32 characters
`secrets.databaseUrl`	`DATABASE_URL`	Async application database connection
`secrets.databaseUrlSync`	`DATABASE_URL_SYNC`	Sync Alembic migration connection
`secrets.defaultAdminEmail`	`DEFAULT_ADMIN_EMAIL`	First-run administrator email
`secrets.defaultAdminPassword`	`DEFAULT_ADMIN_PASSWORD`	First-run administrator password
`secrets.awsAccessKeyId`	`AWS_ACCESS_KEY_ID`	Default S3 provider access key
`secrets.awsSecretAccessKey`	`AWS_SECRET_ACCESS_KEY`	Default S3 provider secret key
`config.awsRegion`	`AWS_REGION`	Default S3 region
`config.awsEndpointUrl`	`AWS_ENDPOINT_URL`	Backend-reachable custom S3 API endpoint
`config.presignedUrlBase`	`PRESIGNED_URL_BASE`	Browser-reachable endpoint used for signed URLs
`config.allowedOrigins`	`ALLOWED_ORIGINS`	JSON array of allowed frontend origins
`config.multipartPartSizeMb`	`MULTIPART_PART_SIZE_MB`	Multipart chunk size in MB
`config.presignedUrlExpiry`	`PRESIGNED_URL_EXPIRY_SECONDS`	Signed URL lifetime in seconds
`secrets.azureTenantId`	`AZURE_TENANT_ID`	Optional Entra tenant
`secrets.azureClientId`	`AZURE_CLIENT_ID`	Optional Entra application ID
`secrets.azureClientSecret`	`AZURE_CLIENT_SECRET`	Optional Entra application secret
`secrets.azureRedirectUri`	`AZURE_REDIRECT_URI`	Entra callback URL

The environment-based S3 connection is the initial default. Add more providers later from Settings → Storage without redeploying.

3. Verify and upgrade

kubectl get pods,svc,ingress -n s3bear
kubectl logs -n s3bear deployment/s3bear-backend
helm status s3bear -n s3bear

helm upgrade s3bear oci://registry-1.docker.io/bearcomp/s3bear \
	--version 1.0.3 \
	--namespace s3bear \
	--values values.production.yaml \
	--atomic

The migration job runs database migrations during deployment. Back up PostgreSQL before a production upgrade and inspect the target chart values for changes.

Next steps

Continue with Configuration, Storage Providers, CORS Setup, or the full HOW-TO guide.