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

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:

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:

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

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

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

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

dotnet --list-sdks

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.