Deploy to Docker

Get up and running quickly with our Docker deployment solution for the Univer service, using Docker Compose for a hassle-free setup.

System Requirements

CPU: Single core
RAM: 2GB
Storage: 10GB

Ensure you have Docker version 23 or higher.

Technical Stack

Our architecture is built on PostgreSQL and RabbitMQ.

Quick start

Compatible with Linux, Mac, and Windows/WSL environments.

bash -c "$(curl -fsSL https://get.univer.ai)"

⚠️

If you encounter any issues during installation or use, please refer to the Troubleshooting.

Confirm that the document service has successfully started.

Access http://localhost:3010 in your web browser to create a new blank document, which will then redirect you to the document link (Internet Explorer is not supported).

Example Image

Also, verify the successful startup of the collaboration service.

For a comprehensive test, try accessing it in various browsers or in private browsing mode to experience the full collaborative capabilities.

Example Image

Service introduction

collaboration-server: collaboration engine server, use OT algorithm to deal edit conflic.
lb: nginx loadbalance component.
universer: univer backend api server, apply http api function for sheet, document, slide.
univer-minio: S3 component, use to storage file content.
univer-postgres: database component.
univer-rabbitmq: MQ component, use in collaboration edit situation.
univer-redis: cache component.
univer-temporal: workflow component, use in import/export situation.
univer-worker-exchange: import/export function component.

Port Check

Ensure that the specified ports are not in use; if they are, terminate the conflicting processes before attempting to start again.

Default ports for Univer services are listed below:

service Name	Port Number	Function
universer	8000	Serves API over HTTP
univer-minio	19000	Acts as the S3 storage server
univer-client	3010	Provides the frontend interface

Offline Deployment

If you need to deploy in an offline environment, we also provide an offline installation package. However, we recommend using the one-click installation script in a networked environment for easier updates.

Download the offline installation package

Click here to download the offline installation package and extract it on your server.

tar -xvf installation-package.tar # Replace 'installation-package' with the actual file name

Start the service

Navigate to the extracted directory and run bash install.sh to start the service.

Verify that the service is available.

Method 1: Start the built-in demo application and visit http://localhost:3010 to see the results.

bash run.sh start-demo-ui

Method 2: Set up your own front-end project. Learn more.

How to uninstall

bash uninstall.sh       # Uninstall while retaining data for future use
bash uninstall.sh clean # Uninstall and delete data

Troubleshooting

Where is the service dir?

In docker-compose dir, include .env config file, run.sh script.

Having trouble starting on a Windows OS?

The run.sh script operates in a bash environment. To get it up and running, you’ll need to use either Git Bash/MinGW or a WSL environment.

Import/Export functionality issue

First, use the browser developer tools to check if the response body during the import/export process contains references to univer-minio. If it does, the issue might be due to improper S3 configuration, leading to import/export functionality issues. Follow the steps below to verify and correctly configure your S3 settings.

Assuming you are using the pre-installed Minio service, open the .env file and modify the S3_ENDPOINT_PUBLIC configuration item according to the instructions below, replacing it with the public or private network IP where the Docker service is running.

- S3_ENDPOINT_PUBLIC=http://univer-minio:9000
+ S3_ENDPOINT_PUBLIC=http://<Public_or_Private_IP_of_Docker_Service>:19000

After making the changes, restart the service to verify the configuration.

Note: Do not set this to localhost or 127.0.0.1, as this will prevent the frontend from accessing the S3 service.

If you are using your own S3 service, you can refer to the complete S3 configuration.

In addition to S3 configuration issues, you should also check whether the import/export API configuration of the Univer Server in the frontend project is correct.

If you even have some problem, can use docker compose logs univer-worker-exchange --since 30m to get log and ask help in community.

How to find error when server start failed?

You can use docker compose logs to see server logs, for example:

# see universer latest 20 minute logs
docker compose logs -f universer --since 20m

How to restart, stop, uninstall server?

# restart server
bash run.sh
 
# stop server
docker compose stop
 
# uninstall
docker compose down
 
# uninstall and clean data
docker compose down --volumes

How to change host port the server used?

You can update the .env file, then run bash run.sh

# host ports
HOST_NGINX_PORT=8000
HOST_MINIO_PORT=19000
HOST_GRAFANA_PORT=13000

How to change database to MySQL?

Required MySQL >= 8.0
Update .env file, set the MySQL config and delete PostgreSQL config.

The docker-compose.mysql.yaml apply a MySQL component, if you want to use yourself database, you can delete the univer-mysql service in docker-compose.mysql.yaml file, and delete the dependencies in other service depends_on properties.
Start/Restart the service: bash run.sh

How to change S3 config to use self component?

Update .env file, set the S3 config.

S3_USER=minio
S3_PASSWORD=minio123456
S3_REGION=us-east-1
S3_PATH_STYLE=true
S3_ENDPOINT=http://192.168.1.100:9000
S3_ENDPOINT_PUBLIC=http://192.168.1.100:9000
S3_DEFAULT_BUCKET=univer

S3_USER=${ACCESS_KEY_ID}
S3_PASSWORD=${ACCESS_KEY_SECRET}
S3_REGION=oss-cn-shenzhen
S3_PATH_STYLE=false
S3_ENDPOINT=https://oss-cn-shenzhen-internal.aliyuncs.com
S3_ENDPOINT_PUBLIC=https://oss-cn-shenzhen.aliyuncs.com
S3_DEFAULT_BUCKET=univer

S3_USER=${ACCESS_KEY_ID}
S3_PASSWORD=${ACCESS_KEY_SECRET}
S3_REGION=us-east-1
S3_PATH_STYLE=false
S3_ENDPOINT=https://s3.amazonaws.com
S3_ENDPOINT_PUBLIC=https://s3.amazonaws.com
S3_DEFAULT_BUCKET=univer

S3_PATH_STYLE: true bucket is in path info; false bucket is in domain info.
S3_REGION: the bucket region, like aws us-east-1.
S3_ENDPOINT: internal network endpoint.
S3_ENDPOINT_PUBLIC: public network endpoint, use to download file.
S3_DEFAULT_BUCKET: s3 bucket, create it before start univer service.

Remove the univer-minio service in docker-compose.yaml file, and delete the dependencies in other service depends_on properties.
Start/Restart the service: bash run.sh

Accessing Port 8000 Returns `404 page not found`

Port 8000 is the API port exposed by the Univer Server. Accessing / and receiving a 404 page not found response is expected because there is no API at that path.

If you want to verify whether the service and functionality are working correctly, you can do so by setting up a start-kit template frontend project.

How to enable CORS ?

Update configs/config.yaml.template file set http config, then restart service:

server:
  http:
    ...
    corsAllowOrigins:
    - "*"

corsAllowOrigins is a string array, support:

”*”: allow all domain CORS, but not support credential headers like authorization, cookie.
[SelfDomainOrigin]: like http://localhost:3010, use domain origin support credential headers.

How to change redis config to use self component?

Update .env file, set the redis config:

REDIS_ADDR=univer-redis:6379
REDIS_USERNAME=
REDIS_PASSWORD=
REDIS_DB=0

REDIS_ADDR: the redis node addr. If use redis cluster, use comma to split multiple addrs, for example REDIS_ADDR=192.168.1.5:6001,192.168.1.5:6002,192.168.1.5:6003,192.168.1.5:6004
REDIS_DB: if use redis cluster, the db always 0.

Remove the univer-redis service in docker-compose.yaml file, and delete the dependencies in other service depends_on properties.
Start/Restart the service: bash run.sh

How to change rabbitmq config to use self component?

Update .env file, set the rabbitmq config:

# single node config
RABBITMQ_HOST=univer-rabbitmq
RABBITMQ_PORT=5672
RABBITMQ_HTTPPORT=15672
RABBITMQ_USERNAME=guest
RABBITMQ_PASSWORD=guest
 
# multiple node config
RABBITMQ_CLUSTER_ENABLED=false
RABBITMQ_CLUSTER_USERNAME=
RABBITMQ_CLUSTER_PASSWORD=
RABBITMQ_CLUSTER_ADDR=
RABBITMQ_CLUSTER_VHOST=/
RABBITMQ_CLUSTER_SCHEMA=amqp

RABBITMQ_CLUSTER_ADDR: use comma to separate multiple addresses, for example: RABBITMQ_CLUSTER_ADDR=192.168.1.2:5672,192.168.1.5:5672,192.168.1.7:5672

Remove the univer-rabbitmq service in docker-compose.yaml file, and delete the dependencies in other service depends_on properties.
Start/Restart the service: bash run.sh

How to deal with “Error response from daemon: Conflict. The container name “/univer-postgres” is already in use by container” error when upgrade the server?

The installation directory has been updated in the new version. You need to stop the old version of the Univer server before proceeding with the upgrade.

docker compose ls
cd /xx/docker-compose
docker compose ps
docker compose down

How to delpoy other version Univer server?

Use the UNIVER_VERSION environment variable to specify the version to download and install. Only versions starting from 0.5.0 are supported.

UNIVER_VERSION=0.5.0 bash -c "$(curl -fsSL https://get.univer.ai)"

Overview Deploy to Kubernetes