ONLYOFFICE DocSpace Server

This repository contains the backend for ONLYOFFICE DocSpace — a room-based collaborative platform for document management.

For the full product overview, see the main repository README. For the frontend setup and architecture, see the client README.

Table of Contents

• Technology Stack
• Project Structure
• Getting Started
  • Prerequisites
  • Quick Start
  • HTTPS & Multi-Portal Dev Setup
  • Launch Profiles
  • Development with VSCode
  • Clear Aspire Docker Artifacts
• Port Allocation
• Testing
  • Database Migrations
• Troubleshooting
• Contributing
• Licensing

Technology Stack

Core

• Language: C# 14.0
• Runtime: .NET 10.0 with ASP.NET Core
• Orchestration: .NET Aspire 13.1
• DI Container: Autofac 10.0
• API Versioning: Asp.Versioning 8.1
• Object Mapping: Riok.Mapperly 4.3

Data & Storage

• Database: MySQL 9.5 (primary), PostgreSQL (supported)
• Caching: Redis (StackExchange.Redis 2.10, FusionCache 2.5)
• Search: OpenSearch
• Storage: Abstracted storage layer with multiple providers

Messaging & Communication

• Message Brokers: RabbitMQ 7.2 (primary), Apache Kafka, ActiveMQ, RedisMQ
• WebSockets: Socket.IO for real-time updates
• Webhooks: Built-in webhook support

Authentication & Security

• Authentication: JWT Bearer, OpenID Connect
• Federation: SAML SSO, Active Directory, LDAP
• Security: IP filtering, brute force protection, 2FA, rate limiting

Observability

• Logging: NLog 5.5 with ElasticSearch, Syslog, AWS CloudWatch targets
• Tracing: OpenTelemetry 1.15 with OTLP exporter
• Health Checks: ASP.NET Health Checks UI for all services

API Documentation

• Swagger: Swashbuckle 10.1
• Interactive Docs: Scalar 2.12

AI

• AI Integration: Mscc.GenerativeAI.Microsoft 2.9

Infrastructure

• Containerization: Docker 28.5+
• Reverse Proxy: OpenResty (Nginx-based)

Project Structure

This project is organized as a .NET solution with a microservices architecture, containing multiple services and shared libraries.

Solution Overview

server/
├── common/                     # Shared libraries and services
│   ├── ASC.AppHost/           # .NET Aspire orchestrator
│   ├── ASC.Api.Core/          # API foundation
│   ├── ASC.Core.Common/       # Core business logic
│   ├── ASC.Common/            # Common utilities
│   ├── ASC.Data.Storage/      # Storage abstraction
│   ├── ASC.Data.Backup.Core/  # Backup core library
│   ├── ASC.Data.Encryption/   # Data encryption
│   ├── ASC.Data.Reassigns/    # User data reassignment
│   ├── ASC.EventBus/          # Event bus (RabbitMQ, ActiveMQ, Redis, Kafka)
│   ├── ASC.FederatedLogin/    # Federation/SSO
│   ├── ASC.Identity/          # Identity management
│   ├── ASC.ActiveDirectory/   # Active Directory integration
│   ├── ASC.IPSecurity/        # IP security
│   ├── ASC.MessagingSystem/   # Internal messaging
│   ├── ASC.Migration/         # Migration core
│   ├── ASC.Resource.Manager/  # Resource management
│   ├── ASC.Socket.IO/         # WebSocket support
│   ├── ASC.SsoAuth/           # SSO authentication
│   ├── ASC.Thumbnails/        # Thumbnail generation
│   ├── ASC.WebDav/            # WebDAV support
│   ├── ASC.Webhooks.Core/     # Webhook support
│   ├── ASC.Analyzers/         # Custom code analyzers
│   ├── services/              # Background services
│   │   ├── ASC.Notify/        # Notification service
│   │   ├── ASC.Studio.Notify/ # Studio notifications
│   │   ├── ASC.Data.Backup/   # Backup service
│   │   ├── ASC.Data.Backup.Worker/  # Backup worker
│   │   ├── ASC.ElasticSearch/ # Search infrastructure
│   │   ├── ASC.ApiSystem/     # API system services
│   │   ├── ASC.TelegramService/    # Telegram integration
│   │   ├── ASC.AuditTrail/   # Audit logging
│   │   └── ASC.ClearEvents/  # Event cleanup
│   └── Tools/                 # Development tools
│       ├── ASC.Migration.Runner/      # DB migration executor
│       ├── ASC.Migrations.Core/       # Migration framework
│       ├── ASC.Api.Documentation/     # API docs generator
│       └── ASC.Data.Stress/           # Stress testing
├── products/                   # Main product modules
│   ├── ASC.Files/             # Document management
│   │   ├── Server/            # Files API (port 5007)
│   │   ├── Worker/            # Files worker (port 5009)
│   │   ├── Core/              # Files business logic
│   │   └── Tests/             # Files tests
│   ├── ASC.People/            # User management
│   │   ├── Server/            # People API (port 5004)
│   │   └── Tests/             # People tests
│   └── ASC.AI/                # AI features
│       ├── Server/            # AI API (port 5157)
│       ├── Worker/            # AI worker (port 5154)
│       └── Core/              # AI business logic
├── web/                        # Web layer
│   ├── ASC.Web.Api/           # Main REST API (port 5000)
│   ├── ASC.Web.Studio/        # Studio backend (port 5003)
│   ├── ASC.Web.Core/          # Shared web core
│   └── ASC.Web.HealthChecks.UI/  # Health monitoring
├── migrations/                 # Database migrations
│   ├── mysql/                 # MySQL migrations
│   │   ├── SaaS/             # SaaS deployment
│   │   └── Standalone/       # Standalone deployment
│   └── postgre/               # PostgreSQL migrations
│       ├── SaaS/
│       └── Standalone/
├── sdk/                        # API SDKs (submodules)
│   ├── docspace-api-sdk-python/
│   ├── docspace-api-sdk-java/
│   ├── docspace-api-sdk-kotlin/
│   ├── docspace-api-sdk-swift/
│   ├── docspace-api-sdk-php/
│   ├── docspace-api-sdk-typescript/
│   ├── docspace-api-sdk-csharp/
│   └── docspace-api-postman-collections/
├── thirdparty/                 # Third-party libraries
├── ASC.Web.sln                 # Main solution
├── ASC.Tests.sln               # Test solution
├── ASC.Migrations.sln          # Migrations solution
└── Directory.Packages.props    # Centralized NuGet versions

Service Responsibilities

ASC.Web.Api — Main REST API

Central API gateway for all DocSpace operations: file operations, user management, room management, settings, authentication. Port: 5000

ASC.Web.Studio — Studio Backend

Backend for the DocSpace web interface: portal management, white-label customization, plugin management. Port: 5003

ASC.Files — Document Management

Core document management: file storage, third-party cloud integrations, document conversion, sharing, permissions, background processing. Ports: 5007 (Server), 5009 (Worker)

ASC.People — User Management

User and group management: profiles, settings, import/export, data reassignment. Port: 5004

ASC.AI — AI Features

AI-powered functionality: AI assistant integration, background AI processing, generative AI support. Ports: 5157 (Server), 5154 (Worker)

ASC.AppHost — Aspire Orchestrator

.NET Aspire host that orchestrates all services and infrastructure: service discovery, Docker container management (MySQL, Redis, RabbitMQ, OpenSearch), development tools (MailPit, DBGate, RedisInsight).

Event Bus

The backend supports multiple message broker implementations:

• RabbitMQ — Primary message broker
• ActiveMQ — Alternative broker
• RedisMQ — Redis-based messaging
• Kafka — High-throughput streaming

API SDKs

Official API SDKs are available as submodules for multiple languages:

• Python, Java, Kotlin, Swift, PHP, TypeScript, C#
• Postman collections for API exploration

Getting Started

Note: This is a development/testing environment, not suitable for production use. For production deployment, see ONLYOFFICE DocSpace Downloads.

Prerequisites

Tool	Version	Verification Command
.NET SDK	10.0	dotnet --version
Docker	>= 28.5.0	docker --version

Quick Start

# From the DocSpace root
cd server/common/ASC.AppHost
dotnet run --launch-profile development

Access:

• Aspire Dashboard: http://localhost:15208
• API Documentation (Scalar): http://localhost:8092/scalar/#ascfiles
• DB Gate: http://localhost:56161
• Mailpit: http://localhost:56162

To run the full application with frontend, see the client README.

HTTPS & Multi-Portal Dev Setup

In addition to plain HTTP on http://localhost:8092, the AppHost exposes the same stack over HTTPS on https://docspace.dev.localhost (port 443). This is what enables cookie-based auth, secure WebSockets, and multi-portal development (each tenant lives on its own subdomain like https://<alias>.dev.localhost).

Everything is set up automatically when Aspire starts — no hosts file edits, no admin actions:

Concern	How it's handled
DNS	The .dev.localhost suffix resolves to 127.0.0.1 via RFC 6761 (browsers) and via a Node preload script ASC.AppHost/scripts/docspace-dns-patch.js injected through NODE_OPTIONS=--require=... for SSR (login/doceditor/management/sdk)
Certificate	A self-signed cert with SAN localhost, *.dev.localhost is generated on first run by DevCertificateGenerator into ASC.AppHost/certs/, valid 2 years, auto-regenerated when expiring or when SAN list changes
Trust	Auto-installed into the Current User Trusted Root store on Windows; into the login keychain on macOS (one password prompt); on Linux the AppHost prints the update-ca-certificates / certutil commands to run manually
TLS termination	OpenResty container listens on 443, proxies to internal HTTP 127.0.0.1:8092 with X-Forwarded-Proto/Host/For/Ssl headers preserved
Forwarded headers	All backend services trust loopback + Docker bridge networks via core:hosting:forwardedHeadersOptions:knownNetworks so Request.Url() sees the original https://... scheme and host
Tenant resolution	core:base-domain is set to dev.localhost in standalone mode → host nct.dev.localhost → tenant alias nct. The default standalone tenant is mapped to docspace.dev.localhost via the CORE__LOCAL_ADDRESSES env var
Next.js dev origins	getAllLocalIps (in client/packages/shared/utils/build.js) injects localhost and *.dev.localhost into allowedDevOrigins, so cross-portal subdomains are accepted by all dev servers

Usage:

• Default portal: https://docspace.dev.localhost
• Add a new portal in the management UI with alias foo, then access it at https://foo.dev.localhost
• HTTP on http://localhost:8092 keeps working in parallel

Resetting the cert (after SAN changes or when the trust marker gets out of sync):

1. Delete server/common/ASC.AppHost/certs/ (the .crt, .key, and .trusted files)
2. On Windows, also remove any stale localhost / docspace.dev.localhost certs from certmgr → Trusted Root Certification Authorities → Current User
3. Restart Aspire — a fresh cert will be issued and re-trusted

Launch Profiles

Navigate to server/common/ASC.AppHost and choose a profile:

Profile	Command	Description
development	dotnet run --launch-profile development	Full development setup with all services
frontend-dev	dotnet run --launch-profile frontend-dev	All backend services, skips client build (for separate frontend dev)
preview	dotnet run --launch-profile preview	Minimal Docker-based setup

Note: Aspire launches multiple services — some run directly, others in Docker containers. Press Ctrl+C to stop all services.

Development with VSCode

1. Install recommended extensions:

• C# Dev Kit — solution explorer, IntelliSense, refactoring
• .NET Aspire — Aspire orchestration support (run/debug from VSCode)

2. Open the solution:

code server/

VSCode will detect ASC.Web.sln automatically via C# Dev Kit. You can also open a filtered solution for faster loading:

• ASC.Web.sln — full solution (all projects)
• ASC.Web.slnx — XML solution format
• ASC.Tests.sln — test projects only
• ASC.Migrations.sln — migration projects only

3. Run and debug:

With the .NET Aspire extension, you can start ASC.AppHost directly from VSCode — press F5 or use the Run and Debug panel (Ctrl+Shift+D). The Aspire extension will orchestrate all services and open the Aspire Dashboard automatically.

To debug a specific service, set breakpoints in the code and attach the debugger to the running process via the Aspire Dashboard or the VSCode debugger.

Clear Aspire Docker Artifacts

Linux/macOS (bash):

docker ps -a --format '{{.Names}}' | grep -E 'mysql|redis|cache-|rabbitmq|messaging-|opensearch|mailpit|dbgate|redisinsight|onlyoffice-editors|openresty' | xargs -r docker stop && \
docker ps -a --format '{{.Names}}' | grep -E 'mysql|redis|cache-|rabbitmq|messaging-|opensearch|mailpit|dbgate|redisinsight|onlyoffice-editors|openresty' | xargs -r docker rm && \
docker volume prune -f && docker network prune -f

Windows (PowerShell):

$c = docker ps -a --format '{{.Names}}' | Where-Object { $_ -match 'mysql|redis|cache-|rabbitmq|messaging-|opensearch|mailpit|dbgate|redisinsight|onlyoffice-editors|openresty' }; if ($c) { $c | ForEach-Object { docker stop $_ }; $c | ForEach-Object { docker rm $_ } }; docker volume prune -f; docker network prune -f

Port Allocation

Service	Port	Description
OpenResty (reverse proxy)	8092	API gateway
Aspire Dashboard	15208	Backend services monitoring
DB Gate	56161	Database management UI
Mailpit	56162	Email testing interface
Web API	5000	Main REST API
Web Studio	5003	Studio backend
People	5004	User management
Notify	5005	Notification service
Studio Notify	5006	Studio notifications
Files	5007	Document management
Files Worker	5009	File processing
API System	5010	System APIs
Backup	5012	Backup service
Clear Events	5027	Event cleanup
Backup Worker	5032	Backup worker
Telegram	5050	Telegram integration
AI	5157	AI service
AI Worker	5154	AI processing
Identity Authorization	8080	Auth service
Identity Registration	9090	Identity service
Socket.IO	9899	WebSocket real-time
SSO Auth	9834	SSO authentication
WebDAV	1900	WebDAV protocol
MySQL	3306	Database server
Redis	6379	Cache server
RabbitMQ	5672, 15672	Message broker + Management UI
OpenSearch	9200, 9600	Search engine

Testing

The test solution (ASC.Tests.sln) contains unit and integration tests for backend services.

# Run all tests
dotnet test ASC.Tests.sln

# Run tests for a specific project
dotnet test products/ASC.Files/Tests/ASC.Files.Tests.csproj

# Run tests for People
dotnet test products/ASC.People/Tests/ASC.People.Tests.csproj

Database Migrations

Migrations are managed per database engine and deployment type:

# Run MySQL standalone migrations
cd common/Tools/ASC.Migration.Runner
dotnet run

Troubleshooting

Port 8092 is already in use

Kill the process using the port:

# macOS/Linux
lsof -ti:8092 | xargs kill -9

# Windows
netstat -ano | findstr :8092
taskkill /PID <PID> /F

Docker containers fail to start

1. Check Docker is running: docker ps
2. Clear Docker artifacts (see Clear Aspire Docker Artifacts)
3. Restart Docker Desktop
4. Try starting backend again

dotnet run fails with SDK version error

Ensure you have .NET 10.0 SDK installed. The global.json specifies rollForward: latestMajor, so any .NET 9.0+ SDK should work, but .NET 10.0 is recommended:

dotnet --list-sdks

Backend services won't stop

Force stop all Docker containers:

docker stop $(docker ps -aq) && docker rm $(docker ps -aq)

For more issues, check our Issue Tracker or Forum.

Contributing

Development Workflow

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/DocSpace.git
3. Create a feature branch: git checkout -b feature/amazing-feature
4. Make your changes
5. Run tests: dotnet test
6. Commit your changes: git commit -m 'Add amazing feature'
7. Push to your fork: git push origin feature/amazing-feature
8. Open a Pull Request

Code Standards

• Follow C# and .NET best practices
• Run dotnet build to ensure no compilation errors
• Write tests for new features
• Keep commits atomic and well-described
• Use centralized package versions from Directory.Packages.props

Commit Message Convention

Follow Conventional Commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test changes
• chore: Build/tooling changes

Licensing

ONLYOFFICE DocSpace is released under AGPLv3 license. See the LICENSE file for more information.

Need help for developers?

Check our official API documentation.