discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens
AsterCommunity/AsterDrive · source
Snapshot 0 · 2026-11-04T12:47:28Z · Rust · Apache-2.0
Content fingerprint
6f1405bfe54961deba53fd7d304bdf91b07493a242a247992444a6db44ee5aeeGitHub description at capture
Self-hosted file infrastructure in Rust for small teams: reliable uploads, storage policies, multiple storage backends, WebDAV/WOPI, and ops tooling.
README at capture
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="frontend-panel/public/static/asterdrive/asterdrive-light.svg" />
<img src="frontend-panel/public/static/asterdrive/asterdrive-dark.svg" alt="AsterDrive" width="320" />
</picture>
</p>
<p align="center">
Self-hosted file infrastructure in Rust for small teams that need storage control, reliable large-file uploads, WebDAV/WOPI, and operations visibility without adopting a full private-cloud suite.
<br />
Route files across local, S3-compatible, and remote-node backends with one dual-licensed Rust + React service built for deployment, auditability, and modification.
</p>
<p align="center">
<a href="https://drive.docs.astercosm.com/"><img alt="Documentation Site" src="https://img.shields.io/badge/docs-Astro_Starlight-7C3AED?style=for-the-badge&logo=astro&logoColor=white"></a>
<a href="README.zh.md"><img alt="中文 README" src="https://img.shields.io/badge/README-中文-E11D48?style=for-the-badge"></a>
<a href="https://drive.docs.astercosm.com/en/start/quick-trial/"><img alt="Quick Start" src="https://img.shields.io/badge/quick%20start-guide-2563EB?style=for-the-badge"></a>
<a href="https://drive.docs.astercosm.com/en/ops/cli/"><img alt="Ops CLI" src="https://img.shields.io/badge/ops-CLI-0EA5E9?style=for-the-badge"></a>
<a href="https://drive.docs.astercosm.com/developer/en/architecture/"><img alt="Architecture" src="https://img.shields.io/badge/architecture-overview-0F172A?style=for-the-badge"></a>
<a href="https://drive.docs.astercosm.com/developer/en/api/"><img alt="API Docs" src="https://img.shields.io/badge/API-reference-059669?style=for-the-badge"></a>
<a href="https://drive.docs.astercosm.com/en/deploy/docker/"><img alt="Docker" src="https://img.shields.io/badge/docker-deployment-2496ED?style=for-the-badge&logo=docker&logoColor=white"></a>
</p>
<p align="center">
<img src="assets/Readme/Screenshot-English.webp" alt="AsterDrive English screenshot" width="1280" />
</p>
## What is AsterDrive?
AsterDrive is a self-hosted file service, dual-licensed under MIT or Apache 2.0, for people who want control over where files live and how they move through the system. It is built around the core drive workflow: upload reliably, organize folders, recover mistakes, share access, connect WebDAV clients, open Office files through WOPI-compatible services, and route objects to the right storage backend.
It is not trying to become a full private-cloud suite. AsterDrive focuses on file infrastructure: storage policies, large-file upload paths, team and personal workspaces, sharing, version history, WebDAV, WOPI, auditability, and deployment/operations tooling.
## Where it fits
AsterDrive is a good fit when you want:
- a single self-hosted service with embedded frontend assets
- SQLite out of the box, with optional PostgreSQL / MySQL later
- local filesystems, object storage, cloud drives such as OneDrive / SharePoint and Google Drive, SFTP, or remote AsterDrive follower-node storage; see the [supported storage backends](https://drive.docs.astercosm.com/en/admin/storage-backends/)
- upload strategies for both small files and large objects: direct, resumable chunked, object-storage presigned, and object-storage multipart
- personal and team workspaces with quotas, shares, trash, tasks, audit logs, and storage policy groups
- WebDAV access with independent accounts and scoped root folders
- Office preview/editing through external WOPI services such as OnlyOffice or Collabora
- a codebase that is meant to be read, modified, and deployed without a plugin marketplace or enterprise stack
AsterDrive is probably not the right first choice when you need:
- a complete collaboration suite with calendars, contacts, chat, mail, and an app ecosystem
- mature native desktop and mobile sync clients today
- an ultra-minimal web UI over a single server directory
- managed database/Redis/object-storage high availability, cross-region strong consistency, automatic cross-region traffic failover, or enterprise compliance guarantees
- a vendor-managed SaaS where someone else owns the deployment and data responsibility
## Design focus
- **File safety first** - trash, version history, locks, quota checks, and cleanup tasks are part of the core workflow, not decorative extras.
- **Storage control** - policy groups route uploads across storage backends with ordered rules, file-category and size constraints, weighted selection, fallback, and dry-run simulation.
- **Large-file paths** - the backend negotiates direct uploads, chunked uploads, object-storage presigned uploads, and object-storage multipart uploads based on policy and object size.
- **Interoperability without sprawl** - WebDAV and WOPI cover practical client and Office workflows without turning the project into an all-in-one cloud suite.
- **Operations built in** - health checks, runtime configuration, audit logs, background tasks, storage tests, `doctor`, and migration commands are first-class features.
- **Hackable core** - Rust backend, React frontend, SeaORM migrations, explicit error codes, API docs, and clear service/repository boundaries.
## Quick start
### Run with Docker
For a local HTTP trial, prepare a writable data directory and start the official image:
```bash
mkdir -p ./data
sudo chown -R 10001:10001 ./data
docker run -d \
--name asterdrive \
-p 127.0.0.1:3000:3000 \
-e ASTER__SERVER__HOST=0.0.0.0 \
-e "ASTER__DATABASE__URL=sqlite:///data/asterdrive.db?mode=rwc" \
-v "$(pwd)/data:/data" \
ghcr.io/astercommunity/asterdrive:latest
```
Open:
```text
http://127.0.0.1:3000
```
Complete the first-start setup screen to create the initial `admin`. Ordinary registration is
available only after setup and never grants the administrator role.
Fresh installations allow the first login over HTTP by default. When the first administrator is created through an HTTPS origin, AsterDrive automatically enables Secure cookies before the following login. For production, keep AsterDrive behind HTTPS and confirm HTTPS-only cookies are enabled in System Settings.
You can also use the included Compose file:
```bash
mkdir -p ./data
sudo chown -R 10001:10001 ./data
docker compose up -d
```
See the [Docker deployment guide](https://drive.docs.astercosm.com/en/deploy/docker/) for the full setup.
### Run from source
```bash
git clone https://github.com/AsterCommunity/AsterDrive.git
cd AsterDrive
cd frontend-panel
bun install
bun run build
cd ..
cargo run
```
On first startup, AsterDrive will automatically:
- generate `data/config.toml` under the current working directory if it does not exist
- create the default SQLite database when using the default database URL
- run all database migrations
- initialize the shared three-stage setup state; after creating the administrator, configure a default storage policy suitable for the deployment
- initialize built-in runtime configuration items in `system_config`
## Production notes
- Do not expose `:3000` directly to the public Internet. Put AsterDrive behind a reverse proxy that handles HTTPS, upload limits, WebDAV/WOPI passthrough, and security headers.
- Configure public site URLs before relying on share links, WebDAV URLs, mail links, or WOPI callbacks.
- Run `./aster_drive doctor` after deployment and upgrades. The default SQLite search acceleration expects `FTS5 + trigram tokenizer` support.
- Plan backups for the database, uploaded blobs, config, and any external object-storage credentials. Start with [Backup and restore](https://drive.docs.astercosm.com/en/ops/backup/).
- If you enable WOPI, test real `docx`, `xlsx`, and `pptx` files through the final public URL and confirm that edits save back into AsterDrive.
## Core capabilities
### File management
- folders, breadcrumbs, list/grid views, search, multi-select, and batch operations
- file upload, folder upload, download, rename, move, copy, delete, restore, and purge
- archive download, online archive compression/extraction, and background task progress
- thumbnails, browser-native previews, read-only ZIP/7z archive manifest previews, and configurable external preview apps
- Monaco-based text editing, lock awareness, version history, restore, and version deletion
### Workspaces and sharing
- personal workspace plus team workspaces
- independent files, shares, trash, tasks, quotas, audit records, and policy groups per workspace
- public file and folder shares at `/s/:token`
- optional share password, expiration time, download limits, open/download counters, and direct links
- shared-folder browsing with child-file download, preview, and thumbnail access
### Access and editing
- HttpOnly cookie auth plus Bearer JWT for API clients
- first-user setup, registration controls, activation, password reset, and email-change confirmation
- WebDAV accounts with independent passwords, scoped root folders, database-backed locks, custom properties, and a small DeltaV subset
- WOPI launch sessions and file endpoints for Office preview/editing through external WOPI hosts
- account security with TOTP, recovery codes, optional email MFA, Passkey / WebAuthn, external identity providers, and login-device management
### Storage and delivery
- storage policies for local filesystems, object storage, cloud drives, SFTP, and remote follower nodes; see the [storage capability matrix](https://drive.docs.astercosm.com/en/reference/storage-matrix/) for backend-specific support
- policy groups with ordered matchers, file-category admission, `first_available` / `weighted_random` placement, fallback, and dry-run simulation
- optional local-only blob deduplication using SHA-256 and reference counting
- object-storage upload/download strategies: `relay_stream`, `presigned`, and multipart uploads
- remote-node upload/download strategies: `relay_stream` and `presigned`
- streaming upload/download paths where the selected strategy allows it
### Administration and operations
- admin overview, users, teams, storage policies, policy groups, remote nodes, shares, tasks, locks, runtime settings, and audit logs
- schema-driven runtime configuration stored in `system_config`
- health endpoints: `/health`, `/health/ready`, optional `/health/memory`, and optional `/health/metrics`
- storage policy and remote-node connection tests
- background task records for archive jobs, thumbnail generation, mail dispatch, cleanup, and runtime tasks
- periodic cleanup for uploads, trash, locks, audit logs, teams, WOPI sessions, and orphaned blobs
- Swagger UI in debug builds with the `openapi` feature, plus static OpenAPI export
## Documentation
The user and deployment documentation is published with Astro Starlight at [drive.docs.astercosm.com](https://drive.docs.astercosm.com/en/).
- [Getting started](https://drive.docs.astercosm.com/en/start/quick-trial/)
- [User guide](https://drive.docs.astercosm.com/en/using/)
- [Workspaces and teams](https://drive.docs.astercosm.com/en/using/workspaces-teams/)
- [Sharing and public access](https://drive.docs.astercosm.com/en/using/sharing/)
- [Preview processing and WOPI](https://drive.docs.astercosm.com/en/admin/preview-processing/)
- [Storage backends](https://drive.docs.astercosm.com/en/admin/storage-backends/)
- [Remote follower storage](https://drive.docs.astercosm.com/en/admin/storage-backends/remote-follower/)
- [Docker deployment](https://drive.docs.astercosm.com/en/deploy/docker/)
- [Production checklist](https://drive.docs.astercosm.com/en/ops/launch-checklist/)
- [Backup and restore](https://drive.docs.astercosm.com/en/ops/backup/)
- [Operations CLI](https://drive.docs.astercosm.com/en/ops/cli/)
- [Developer docs](https://drive.docs.astercosm.com/developer/en/)
- [Architecture](https://drive.docs.astercosm.com/developer/en/architecture/)
- [API overview](https://drive.docs.astercosm.com/developer/en/api/)
## Security
- Report vulnerabilities privately through [GitHub Security Advisories](https://github.com/AsterCommunity/AsterDrive/security/advisories/new) or `report@esaps.net` — see [SECURITY.md](SECURITY.md) for the full policy
- Published advisories: [github.com/AsterCommunity/AsterDrive/security/advisories](https://github.com/AsterCommunity/AsterDrive/security/advisories)
- `security.txt` (RFC 9116): [drive.docs.astercosm.com/.well-known/security.txt](https://drive.docs.astercosm.com/.well-known/security.txt)
## Development
### Requirements
- Rust `1.95.0+`
- cargo-nextest
- Bun
- Node.js `>=26.13.0 <27` for frontend and documentation tooling; `.nvmrc` and the Docker frontend build pin `26.13.0`
### Common commands
```bash
# Backend
cargo run
cargo check
cargo nextest run
cargo nextest run --features openapi --test generate_openapi
# Frontend
cd frontend-panel
bun install
bun run dev
bun run build
bun run check
```
### Notes
- Type checking uses the TypeScript 7 native `tsc` compiler
- Linting uses `biome`, not ESLint
- TypeScript `enum` is not allowed; use `as const` objects
- Type-only imports must use `import type`
## Project structure
```text
src/ Rust application, services, API, and runtime
crates/aster_drive_metrics/ Product metrics contracts and AsterForge adapters
crates/aster_drive_migration/ SeaORM migrations
crates/aster_drive_model/ Shared product models and SeaORM entities
crates/aster_drive_storage/ Storage contracts, descriptors, and structured errors
frontend-panel/ React admin/file panel
docs/ Deployment and end-user documentation
developer-docs/ API, architecture, testing, and internal positioning docs
tests/ Integration tests
```
## License
Licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option. Copyright (c) 2026 AsterCommunity & AptS-1547.