Corestore is the node-local storage provider for serve.zone workloads. One process starts a SmartDB database endpoint, a SmartStorage S3-compatible endpoint, a Coreflow-facing control API, and a Docker VolumeDriver plugin backed by local disk and @serve.zone/containerarchive snapshots.

Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit community.foss.global/. This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a code.foss.global/ account to submit Pull Requests directly.

What It Provides

Corestore packages the storage primitives that a workload usually needs on a serve.zone node:

Database: @push.rocks/smartdb exposes a MongoDB-compatible endpoint on port 27017.
Object storage: @push.rocks/smartstorage exposes an S3-compatible endpoint on port 9000.
Control API: HTTP JSON API on port 3000 for provisioning, deprovisioning, metrics, snapshots, restores, and archive object replication.
Docker volumes: Docker's legacy VolumeDriver API over /run/docker/plugins/corestore.sock.
Backups: @serve.zone/containerarchive stores deduplicated volume snapshots under the Corestore data directory.

Corestore is deliberately node-local. Volume data lives on the node where Docker mounts it, and the Docker driver reports Scope: local.

Runtime Layout

Default data root:

/data/corestore

Inside that root Corestore creates:

Path	Purpose
`smartdb/`	SmartDB file storage and SmartDB user data.
`smartstorage/`	S3-compatible object data.
`volumes/`	Docker volume mountpoints.
`volume-archive/`	ContainerArchive repository for volume snapshots.
`corestore-manifest.json`	Service, resource, volume, and snapshot manifest.
`corestore-secret.json`	Persisted master secret and derived admin credentials.

The master secret is generated on first start unless CORESTORE_MASTER_SECRET is provided. Tenant DB and S3 credentials are derived deterministically from that secret and the service id.

Configuration

Env var	Default	Purpose
`CORESTORE_DATA_DIR`	`/data/corestore`	Persistent data root.
`CORESTORE_BIND_ADDRESS`	`0.0.0.0`	Bind address for control, S3, and DB endpoints.
`CORESTORE_PUBLIC_HOST`	`corestore`	Hostname written into generated service credentials.
`CORESTORE_CONTROL_PORT`	`3000`	Control API port.
`CORESTORE_S3_PORT`	`9000`	S3 endpoint port.
`CORESTORE_DB_PORT`	`27017`	Mongo-compatible DB endpoint port.
`CORESTORE_REGION`	`us-east-1`	Region value for S3 credentials.
`CORESTORE_API_TOKEN`	unset	Optional token required for all control APIs except `/health`.
`CORESTORE_MASTER_SECRET`	generated and persisted	Seed for deterministic tenant credentials.
`CORESTORE_DB_ROOT_USER`	`corestore_root`	SmartDB root username.
`CORESTORE_DB_ROOT_PASSWORD`	derived or persisted	SmartDB root password override.
`CORESTORE_S3_ADMIN_ACCESS_KEY_ID`	derived or persisted	SmartStorage admin access key override.
`CORESTORE_S3_ADMIN_SECRET_ACCESS_KEY`	derived or persisted	SmartStorage admin secret override.
`CORESTORE_VOLUME_PLUGIN_SOCKET`	`/run/docker/plugins/corestore.sock`	Docker VolumeDriver socket path.
`CORESTORE_ARCHIVE_PASSPHRASE`	unset	Optional ContainerArchive encryption passphrase.
`CORESTORE_VERBOSE`	`false`	Enables verbose SmartStorage logging when set to `true`.

When Coreflow creates the global Corestore service, it forwards its own CORESTORE_API_TOKEN into the service. Use the same token in Coreflow and Corestore to protect provisioning APIs from other containers on the overlay network.

Starting Corestore

pnpm install
pnpm build
pnpm start

For TypeScript development:

pnpm run startTs

Programmatic startup:

import { CoreStore } from '@serve.zone/corestore';

const corestore = new CoreStore({
  dataDir: '/var/lib/serve.zone/corestore',
  apiToken: process.env.CORESTORE_API_TOKEN,
});

await corestore.start();

Control API

GET /health is always unauthenticated:

curl http://corestore:3000/health

All other control endpoints require either Authorization: Bearer <token> or x-corestore-token: <token> when CORESTORE_API_TOKEN is configured.

Useful endpoints:

Method	Path	Purpose
`GET`	`/metrics`	Returns database, object storage, and volume metrics.
`GET`	`/volumes`	Lists managed Docker volumes.
`GET`	`/volumes/snapshots?name=<volume>`	Lists snapshots for one volume or all volumes.
`POST`	`/volumes/create`	Creates or updates a named managed volume.
`POST`	`/volumes/remove`	Removes an unmounted volume.
`POST`	`/volumes/snapshot`	Creates a ContainerArchive snapshot of a volume.
`POST`	`/volumes/restore`	Restores a snapshot into a volume.
`GET`	`/resources`	Lists provisioned per-service DB/S3 resources.
`POST`	`/resources/provision`	Provisions database and/or object storage for a service.
`POST`	`/resources/deprovision`	Deletes provisioned DB/S3 resources for a service.
`POST`	`/resources/snapshot`	Snapshots service DB/S3 resources.
`POST`	`/resources/restore`	Restores service DB/S3 resources.
`POST`	`/archive/manifest`	Returns a manifest for the local archive repository.
`POST`	`/archive/object/read`	Reads an archive object as base64 with size and SHA-256.
`POST`	`/archive/object/write`	Writes a validated archive object from base64.

Provision resources for a service:

curl -X POST http://corestore:3000/resources/provision \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <CORESTORE_API_TOKEN>' \
  -d '{"serviceId":"svc-123","serviceName":"api","capabilities":["database","objectstorage"]}'

The response includes service-specific environment variables such as MONGODB_URI, S3_BUCKET, AWS_ACCESS_KEY_ID, and AWS_ENDPOINT_URL.

Snapshot a volume:

curl -X POST http://corestore:3000/volumes/snapshot \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <CORESTORE_API_TOKEN>' \
  -d '{"name":"sz-api-data-abc123","snapshotName":"before-deploy"}'

Restore a volume snapshot:

curl -X POST http://corestore:3000/volumes/restore \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer <CORESTORE_API_TOKEN>' \
  -d '{"name":"sz-api-data-abc123","snapshotId":"<snapshot-id>","clear":true}'

Docker Volume Driver

Corestore implements these Docker VolumeDriver endpoints over its Unix socket:

/Plugin.Activate
/VolumeDriver.Capabilities
/VolumeDriver.Create
/VolumeDriver.Remove
/VolumeDriver.Mount
/VolumeDriver.Unmount
/VolumeDriver.Path
/VolumeDriver.Get
/VolumeDriver.List

The Corestore service must bind mount /run/docker/plugins from the host so Docker can discover /run/docker/plugins/corestore.sock.

Volume mountpoints are real host directories under:

<CORESTORE_DATA_DIR>/volumes/<safe-volume-name>-<hash>/data

Docker bind-mounts those paths into workload containers. Corestore tracks mount ids, service metadata, backup flags, and snapshot history in corestore-manifest.json.

Coreflow Integration

The intended platform behavior is:

Coreflow deploys Corestore as a global service so each workload node has a local storage provider.
Workload platform bindings for database and objectstorage call /resources/provision.
First-class workload volumes use Docker DriverConfig.Name = 'corestore' by default.
Returned environment variables are merged into the workload Docker secret before service creation.
Backup orchestration snapshots volumes through /volumes/snapshot and service resources through /resources/snapshot.
Restore orchestration uses /volumes/restore, /resources/restore, and archive object read/write endpoints.

Docker Image

pnpm run build:docker

The image exposes 3000, 9000, and 27017 and stores runtime data under /data/corestore unless CORESTORE_DATA_DIR overrides it.

Development

Common commands:

pnpm install
pnpm build
pnpm test
pnpm run watch

Important files:

Path	Purpose
`ts/index.ts`	CLI startup wrapper exporting `CoreStore`, `runCli`, and `stop`.
`ts/corestore.classes.corestore.ts`	Main runtime, control API, VolumeDriver API, provisioning, snapshots, and archive replication.
`ts/corestore.interfaces.ts`	Request, response, manifest, resource, and snapshot types.
`ts/corestore.plugins.ts`	Centralized dependency imports.

License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the license file.

Please note: The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

readme.md

@serve.zone/corestore