Skip to main content

storage-service

storage-service stores files for a Shellui company and serves them through /storage/v1/. You upload an object, then download it with a JWT or a share link.

What storage-service is​

storage-service is the Shellui file API. It keeps one bucket per company, stores the bytes in S3 or on the local filesystem, and records who may read or change each path. The same process serves the API, Django admin, WebDAV, and OpenAPI.

It is a Django app, published as the shellui/storage-service Docker image. It checks JSON Web Tokens (JWTs) issued by identity-service. It does not sign people in itself.

Routes follow the Supabase Storage path shape (/storage/v1/object/…, /storage/v1/bucket). The optional apikey header is accepted and ignored. The Bearer JWT is what authorizes the call.

Who it is for​

Use it when a Shellui app needs company files: the Files UI, a script, or a WebDAV client. Company owners set quotas and Shellui Actions webhook rules. Operators run the process, the database, the blob store, and Redis.

Your product stays in the shell. storage-service does not replace identity-service, hosting-service, or email-service.

What it stores and serves​

Each company has one system bucket named company. The first request that needs it creates that bucket. You do not create extra buckets through the API.

A file is a StorageObject: a path such as docs/report.pdf, a size, a MIME type, an owner, and a blob key in the backend. Folders are prefixes. An empty folder is a marker object named .emptyFolderPlaceholder.

The default blob backend is the local filesystem. Set STORAGE_BACKEND=s3 to use an S3-compatible bucket (AWS, MinIO, Cloudflare R2, OVH, and others). Downloads of objects you are allowed to read stream through Django. Anonymous public buckets are off.

How it fits with identity, hosting, and email​

identity-service signs people in and issues the Bearer JWT you send on API calls. storage-service has no user table. company_id, user_id, and staff flags come from that token. See JWT and claim trust.

hosting-service stores deployment archives in its own filesystem or bucket. storage-service does not receive those archives and does not call hosting-service.

storage-service does not send mail itself. When EMAIL_SERVICE_API_KEY is set, it forwards each storage event to email-service, which sends mail only after that company enables a rule. A share link is a URL you send yourself. Company owners attach HTTPS endpoints with Shellui Actions webhooks, and every storage event is stored in the event log.

Upload and download flow​

A signed-in caller with company_id in the token uses the company bucket:

  1. The first request provisions the company bucket and emits storage.bucket.created.
  2. POST or PUT /storage/v1/object/company/{path} writes the bytes. A new file is private to the creator until you share it.
  3. GET on that path streams the bytes when the caller may read it. Cache-Control is private, no-store.
  4. A share link (/storage/v1/share/link/{token}) lets someone without a token download that one file until the link expires, hits its download cap, or you revoke it.

WebDAV at /dav/company/… uses the same quotas, grants, and upload signals. A direct S3 client pointed at the raw bucket does not.

Access and tenancy​

Every object row stores company_id from the JWT. You only see that company's bucket. There is no hosting-style waitlist: a token with company_id can use storage, inside the quota.

New files and folders are private to the creator. Access grants then allow or deny a user, or the whole company, on a folder or a file. Nested paths inherit the parent folder's grants.

Staff and company owners change quotas and read Shellui Actions routes. Other members use the files their grants allow.

Webhooks and the event log​

Provisioning the company bucket, uploading or overwriting a file, and deleting a file each write an event. Folder placeholder objects are omitted. Matching Shellui Actions webhook rules receive a signed POST. Delivery is at-least-once. The in-container retry_webhooks job retries failures. There is no separate actions service.

The same job retries the email-service forward. That body omits sign-in links, tokens, signed URLs, and secret-shaped fields. Webhook envelopes omit the same fields. See Email notifications.

The event log keeps those events for EVENT_LOG_RETENTION_DAYS (default 7).

Configure and run​

Copy .env.example to .env, set SECRET_KEY, point IDENTITY_SERVICE_URL at identity-service, and run migrations. Docker Compose is the local path in Run storage-service.

The container runs database migrations, then Gunicorn and a Celery worker with beat. That worker runs retry_webhooks every minute and purge_expired_data every hour. REDIS_URL is required when DEBUG=false. With DEBUG=true and no Redis, the web app still starts and the jobs do not run.

Where to go next​

Pick the row that matches what you are doing:

You want toStart with
Run it locallyRun storage-service
Set environment variablesConfiguration
See how files and folders are storedBuckets, folders, and files
Share a folder inside the companyAccess grants
Send one file to someone without an accountShare links
Set a company or per-user capQuotas
Stream a download or sign an S3 URLDownloads and signed URLs
Mount the bucket in a file clientWebDAV
See which JWT claims are trustedJWT and claim trust
Call an HTTPS endpoint on uploadWebhooks and n8n
Forward an event to email-serviceEmail notifications
Read past storage eventsEvent log
Lock down a production installSecurity hardening
See scheduled retries and retentionScheduled jobs
Browse the HTTP APIAPI reference

Source and the changelog are on GitHub. These pages are built from docs/ by shellui/shellui and published on docs.shellui.com at docs.shellui.com/storage.