Initialization, Backup, and Upgrade

This document details the operations for first-time initialization, exporting backups, importing and restoring, and upgrading SurveyKing Community Edition v1.12.0.

Use Cases

• After initial deployment, you navigate to /setup in your browser.
• You are preparing to upgrade, migrate a server, or change the deployment method.
• You need to regularly back up system data to prevent accidental deletion or data loss due to server failure.

warning

Before upgrading, migrating, or importing backups, export a backup package and save it to your computer. Do not only store the backup on the original server.

Initializing the System

1. Open /setup

After deployment, open the access address provided in the deployment documentation in your browser.

If the system has not been initialized, it will automatically go to the /setup page. If it does not redirect automatically, you can manually visit:

http://your_access_address/setup

Image Placeholder

Screenshot: The system opens to the /setup page for the first time, annotating the locations of "H2 Built-in Database," "MySQL Database," and "Next." Filename: setup-select-database.png

2. Select a Database

Selection	Suitable Scenario
H2 Built-in Database	Trial, small demonstrations, do not want to install MySQL
MySQL Database	Official use, multiple users, data is important

tip

For official use, we recommend selecting MySQL. H2 is more suitable for initially testing features.

3. Fill in MySQL Information

If you select MySQL Database, first choose the deployment method and then fill in the database connection information.

Common filling methods:

Deployment Method	Database Address	Port Number	Database Name	Username	Password
Docker Compose One-Click Script	mysql	3306	surveyking	surveyking	Password in surveyking/.env
Synology NAS / fnOS NAS Compose	mysql	3306	surveyking	root	surveyking
aaPanel Manual / Linux Manual	localhost	3306	surveyking	User you created	MySQL password you set
External MySQL	MySQL Address	3306	Your database name	MySQL Username	MySQL Password

After filling in the information, click Test Connection. Continue only after the test is successful.

warning

When using Docker Compose and NAS deployments, the MySQL port in /setup is usually 3306, not 33060. 33060 is used for external connections to MySQL from the NAS or server.

4. Fill in System Information

Fill in the information as prompted on the page:

Configuration Item	Description
System Name	Name displayed in the login page and browser title bar
System Description	Optional
Default Language	Defaults to Simplified Chinese
Open Registration	Disable if unsure
AI Configuration	You can disable it first, then enable it later in system settings

Confirm the information and click Start Initialization.

• Select H2: After initialization is complete, click Enter System.
• Select MySQL: The system will automatically restart. After restarting, you will be redirected to the login page.

Default account:

Item	Default Value
Account	admin
Password	123456

After logging in for the first time, immediately go to System Management → Personal Settings → Security Settings and change the default password.

Exporting Backups

1. Enter Data Backup

Log in to the system as an administrator and go to System Management → System Settings.

Find Data Backup at the bottom of the page.

Image Placeholder

Screenshot: System Management → System Settings page, annotating "Data Backup," "Export Backup," and "Import Backup" buttons. Filename: system-setting-backup.png

2. Click Export Backup

Click Export Backup to download a .zip file in your browser. The filename will be similar to:

surveyking-backup-20260502_153000.zip

The backup package contains:

Content	Description
manifest.json	Backup manifest, version, and source information
data/*.ndjson	Data for each table
files/	Uploaded attachments directory

warning

Do not manually modify files in the backup package. The backup content will be verified during import, and failure to do so may prevent recovery.

3. Save the Backup Package

It is recommended to save at least two copies:

• One on your computer or external hard drive.
• One on a cloud disk, object storage, or another server.

If you are going to upgrade the system, first confirm that the backup package has been downloaded before proceeding.

Importing and Restoring

1. Prepare the Target System

First deploy and initialize a runnable SurveyKing system.

If migrating to a new server, it is recommended that the target system version be the same as or higher than the original system version. Do not import backups from newer versions into older systems.

2. Upload the Backup Package

Go to System Management → System Settings → Data Backup and click Import Backup. Select the previously exported .zip file.

The system will prompt "Importing backup will overwrite current system data." Confirm that this is correct and click Continue Import.

danger

Importing backups will overwrite the same data tables and uploaded file directories in the current system. Before importing, first export a backup of the current system.

3. Check the Import Results

After successful import, the system will prompt how many tables, data rows, and files were restored.

If you are prompted that some tables were skipped, it is usually because the target system does not have the corresponding data table due to version incompatibility. First confirm the target system version before deciding whether to redeploy to a more suitable version.

Upgrading the System

1. Recommended Method: Redeploy New Version

For users who are not technically proficient, the most reliable upgrade method is to redeploy a new version and then import the backup.

Steps:

1. In the old system, go to System Management → System Settings → Data Backup, and click Export Backup.
2. Redeploy a new version of SurveyKing according to the deployment documentation.
3. Open the new system and first complete /setup initialization.
4. Log in to the new system, go to System Management → System Settings → Data Backup, and click Import Backup.
5. Check projects, users, questionnaires, and uploaded attachments for completeness.
6. After confirming that everything is correct, disable the old system or switch domains.

The advantage of this method is that the old system remains available, so if the upgrade fails, you can revert to the old system.

2. In-Place Upgrade

If you are familiar with the current deployment method, you can also perform an in-place replacement.

Deployment Method	Upgrade Action
Docker Compose	Execute docker compose pull followed by docker compose up -d
Single Docker Container	Delete the old container after docker pull, then restart with the original mount directory
Windows One-Click Package	Stop the old program, extract the new version, start the new version and import the backup
aaPanel / Linux	Stop the project, replace the new jar file, then start the project
NAS Compose	Re-pull the image in the Compose project or rebuild and start the project

warning

Before performing an in-place upgrade, be sure to export a backup first. Do not directly delete containers, directories, or replace databases without a backup.

3. Is it Necessary to Execute Database Scripts?

First check Open Source Version Updates and Open Source Changelog.

If the update instructions require executing database upgrade scripts, execute them in version order. For example, from v1.6 to v1.8, first execute v1.6 -> v1.7, then execute v1.7 -> v1.8.

If the update instructions do not require executing scripts, usually just update the program and restart.

Common Questions

Can I re-enter /setup after initialization?

It cannot be normally repeated.

After initialization is complete, the system will go to the login page. System name, registration settings, and AI configuration can be modified in System Management → System Settings.

If you need to reinitialize, it is recommended to redeploy an empty system and then import the required backup.

Can a backup package from H2 be restored to MySQL?

You can try, provided that the target system version is the same as or higher than the original system version.

A more reliable approach:

1. Deploy a new system using MySQL.
2. Complete /setup initialization.
3. In the new system, import the backup package exported from the H2 system.
4. Check projects, users, questionnaires, and attachments for completeness.

Will importing a backup overwrite current data?

Yes.

Importing backups will overwrite the same data tables and uploaded file directories in the current system. Export a backup of the current system before importing.

Does the backup package include uploaded images and attachments?

Yes.

The files/ directory in the backup package is the system's uploaded files directory. The directory will also be restored together during import.

What if the system can no longer open?

If the system page cannot be opened, first contact technical personnel for server-level backups.

You need to back up at least:

Deployment Method	Key Backup Content
Docker Compose	MySQL data volume or mysql/data, files
Single Docker Container	Mounted db, files, and logs directories
Windows One-Click Package	Database and uploaded files directory in the extracted directory
Linux Manual	/opt/surveyking/db, /opt/surveyking/files, MySQL database
NAS Compose	mysql/data and files directories in the project directory