Appsmithctl

Appsmith comes with an appsmithctl command line utility. You can use it for managing and maintaining your Appsmith instance.

appsmithctl <subcommand> <options>

How To Use Appsmithctl For Instance Management

Subcommands

Subcommands allow you to trigger different operations like exporting or importing databases.

Subcommand	Description
--help	Show help.
ex, export_db	Export internal database.
im, import_db	Import internal database.
mi, migrate	Migrate to a new server.
crs, check_replica_set	Check Replica Set MongoDB.
backup	Create a backup of the Appsmith instance.
restore	Restore the Appsmith instance from a backup.

info

With Business Edition, you can also sync the backups to an AWS S3 bucket.

Export Database

Use the following command to backup Appsmith's database.

info

You can restore the backups onto another instance using the import command to restore data.

ex, export_db

Before running this, ensure you are in the directory where docker-compose.yml is located.

docker-compose exec appsmith appsmithctl export_db

The output file will be stored in the container directory /appsmith-stacks/data/backup/appsmith-data.archive. Thanks to the volume configuration in the docker-compose.yml file, it should be available on your host machine at ./stacks/data/backup/appsmith-data.archive.

If your volume configuration is different or unavailable, you can use the following command to copy the archive file to your host disk:

docker cp appsmith:/appsmith-stacks/data/backup/appsmith-data.archive .

info

You may want to save the docker.env file in addition to this archive file if you intend to be able to reproduce this environment elsewhere in case of a disaster,

The docker.env file can be copied from the container with the following command:

docker cp appsmith:/appsmith-stacks/configuration/docker.env .

note

Please save the encryption environment variables APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALTvalues, from docker.env because the backup archive does not include them for security reasons.

Import Database

The following command can restore the backup archive created by the export command.

im, import_db

• First, copy the archive file into the container using the following command:

docker cp ./appsmith-data.archive appsmith:/appsmith-stacks/data/restore/

• Second, run the following command to import data from this file:

docker-compose exec appsmith appsmithctl import_db

info

You may also want to copy the docker.env from the original instance into this one when you restore.

• Copy the docker.env file using the below command:

tip

If you are in the installation folder and docker.env exists in the same folder. If not, please append the path where the file resides to the below command.

docker cp ./docker.env appsmith:/appsmith-stacks/configuration/

• Restart the Appsmith server using the following command:

docker-compose exec appsmith supervisorctl restart backend

Backup Appsmith Instance

Use the following command to create a backup archive of the Appsmith instance. The backup includes the database, docker.env data, and Git data.

backup

Use the command to backup the archive.

info

The backed-up archive can then be used to restore an Appsmith instance to the previous state using the restore command.

Before running this, ensure you are in the docker host root directory where docker-compose.yml is located.

docker-compose exec appsmith appsmithctl backup

The archive file will be stored in the container directory /appsmith-stacks/data/backup/. Thanks to the volume configuration in the docker-compose.yml file, it should be available on your host machine at ./stacks/data/backup/

danger

Please save the encryption env values, APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALT, from docker.env because the backup archive does not include them for security reasons

Optional arguments for backup

Sync Backup (only for Business Edition)

appsmithctl backup --upload-to-s3

You can choose to sync backups to an AWS S3 bucket (only for Business Edition).

• Add the below entries to the docker.env file to enable the sync:

APPSMITH_BACKUP_S3_ACCESS_KEY=<aws access key> 
APPSMITH_BACKUP_S3_SECRET_KEY=<aws secret key>
APPSMITH_BACKUP_S3_BUCKET_NAME=<bucket name> 
APPSMITH_BACKUP_S3_REGION=<aws bucket region>

• Use the --upload-to-s3 option for the backup command. The backup command reads bucket details set in the environment variables above and uploads the backup to it.

info

Once configured correctly, the restore command automatically lists the backups in the bucket and the local backups in the CLI menu.

Restore Appsmith instance

The following command can be used to restore an Appsmith instance from a backup archive.

restore

docker-compose exec appsmith appsmithctl restore

The command first lists all the backup archives in the directory /appsmith-stacks/data/backup/ in ascending/chronological order (the most recent backup archive at the bottom).

note

You may see a warning if you restore an instance with an older Appsmith version. You can follow the instructions to update the docker-compose.yml file with the correct Appsmith image corresponding to the instance to be restored.

Enter the index of the corresponding backup archive you want to use to restore.

In the restored instance, you may use the existing encryption environment variables APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALT of the current Appsmith instance. You can also choose to add the corresponding variables to the backed-up instance.