Deploying with 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

1. CPU: Single core
2. RAM: 2GB
3. Storage: 10GB

Ensure you have Docker version 23 or higher (opens in a new tab).

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)"

Confirm that the document service has successfully started.

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

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.

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:

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.

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

bash run.sh start-demo-ui

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?

1. Required MySQL >= 8.0

2. Update .env file, set the MySQL config and delete PostgreSQL config.

3. 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.

4. Start/Restart the service: bash run.sh

How to change S3 config to use self component?

1. 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_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.

2. Remove the univer-minio service in docker-compose.yaml file, and delete the dependencies in other service depends_on properties.

3. 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?

1. 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.

2. Remove the univer-redis service in docker-compose.yaml file, and delete the dependencies in other service depends_on properties.

3. Start/Restart the service: bash run.sh

How to change rabbitmq config to use self component?

1. 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

2. Remove the univer-rabbitmq service in docker-compose.yaml file, and delete the dependencies in other service depends_on properties.

3. Start/Restart the service: bash run.sh