Restore Instance

This page explains how to restore your self-hosted Appsmith instance backup using the appsmithctl utility.

Prerequisites

Before starting, ensure the following:

• Your self-hosted Appsmith instance is running. If you haven’t already installed Appsmith, refer to the Installation guides. This guide assumes you are working with an existing installation.
• Ensure you have at least 2 GB of free storage available to perform restore tasks.
• Ensure that you have the appropriate access to execute docker-compose, kubectl, or supervisorctl commands, depending on your deployment setup.
• Verify that the backup archive file you want to restore is available.

Restore instance backup

Follow the appropriate instructions based on your deployment environment:

Docker

Follow these steps to restore your Appsmith instance for Docker-based installations:

1. Copy the backup archive file:

   docker cp appsmith-backup-TIMESTAMP.tar.gz.enc appsmith:/appsmith-stacks/data/backup/

2. Restore the Appsmith instance:

   docker-compose exec -it appsmith appsmithctl restore

   The command lists available backup archives, with the latest appearing at the bottom.

3. Select a backup archive from the list to restore.

   

   Select a backup archive while restoring Appsmith instance

   Attention

   If you are restoring an older version of Appsmith, a warning message may appear. Update the docker-compose.yml file with the Appsmith image version you wish to restore.

4. When prompted, enter the password you entered when creating the backup. This password is required to restore the backup. The restore command restores the backup and restarts the Appsmith server to apply the changes.

Kubernetes

Follow these steps to restore your Appsmith instance for Kubernetes-based installations:

1. Retrieve the name of the Appsmith pod:

   kubectl get pods

2. Copy the backup archive file to the pod. Replace ANY_APPSMITH_POD_NAME with the pod name:

   kubectl cp appsmith-backup-TIMESTAMP.tar.gz.enc ANY_APPSMITH_POD_NAME:/appsmith-stacks/data/backup/

3. Restore the backup. Replace ANY_APPSMITH_POD_NAME with the pod name:

   kubectl exec -it ANY_APPSMITH_POD_NAME -- appsmithctl restore

4. When prompted, enter the password you entered when creating the backup. This password is required to restore the backup.

5. Restart the Appsmith pods based on your setup:

   • If autoscaling is turned on:

     kubectl rollout restart deployment appsmith

   • If autoscaling is turned off, or you’re using the Community Edition, the restore command restores the backup and restarts the Appsmith server to apply the changes.

Automate restores

Starting with Appsmith v2.4.1, you can run appsmithctl restore without prompts for automated disaster recovery or environment rebuilds.

appsmithctl restore --non-interactive --backup-file=appsmith-backup-TIMESTAMP.tar.gz.enc

Select the backup

Use --backup-file=<name> with the exact archive filename, including its extension. The command does not automatically select the latest backup.

Copy the archive to /appsmith-stacks/data/backup/ inside the container or pod using the steps above. For instances with S3 backups configured and an active paid plan, the command also checks S3. It uses the local archive when the filename exists in both locations; otherwise, it downloads the matching S3 archive before restoring it.

Supply the required secrets

The required environment variables depend on the archive format:

Archive	Required secrets
Encrypted (.tar.gz.enc)	Set APPSMITH_BACKUP_ARCHIVE_PASSWORD to the password used when creating the archive. Appsmith restores the instance encryption keys from the encrypted backup.
Unencrypted (.tar.gz)	Set both APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALT to the values from the instance that created the backup. The archive password is not required.

Supply the archive password as a temporary secret for the restore invocation, using your CI/CD secret store. Do not save it in docker.env, Helm values, or source control. If APPSMITH_BACKUP_ARCHIVE_PASSWORD is set, Appsmith uses it for one decryption attempt, even in interactive mode.

For an unencrypted backup from the same instance, you can use its existing encryption password and salt. When restoring another instance's backup, supply that source instance's values before running the command. The command checks that both values are present; you must ensure they match the source instance.

Run the restore

The following examples restore an encrypted archive. Replace TIMESTAMP, the container or pod name, and the namespace with your values.

Docker

Configure your pipeline to inject APPSMITH_BACKUP_ARCHIVE_PASSWORD into the runner's environment, then pass it to the restore process:

docker exec \
  -e APPSMITH_BACKUP_ARCHIVE_PASSWORD \
  appsmith appsmithctl restore \
  --non-interactive \
  --backup-file=appsmith-backup-TIMESTAMP.tar.gz.enc

Do not allocate a TTY (-t) for pipeline execution. To use Docker Compose, replace docker exec with docker-compose exec -T in this example.

For an unencrypted archive, use the .tar.gz filename and omit -e APPSMITH_BACKUP_ARCHIVE_PASSWORD. If supplying the source instance's encryption keys from the runner, pass them with -e APPSMITH_ENCRYPTION_PASSWORD -e APPSMITH_ENCRYPTION_SALT.

Kubernetes

Make APPSMITH_BACKUP_ARCHIVE_PASSWORD available to the restore process in the target pod through your Kubernetes secret management workflow. Setting it only on the machine running kubectl does not pass it into the pod. Limit its availability to the recovery operation and remove the temporary secret configuration afterward.

kubectl exec -n APPSMITH_NAMESPACE ANY_APPSMITH_POD_NAME -- \
  appsmithctl restore \
  --non-interactive \
  --backup-file=appsmith-backup-TIMESTAMP.tar.gz.enc

For an unencrypted archive, use the .tar.gz filename and ensure the restore process has the source instance's APPSMITH_ENCRYPTION_PASSWORD and APPSMITH_ENCRYPTION_SALT.

After a successful restore, if autoscaling is turned on, restart the Appsmith deployment:

kubectl rollout restart deployment appsmith -n APPSMITH_NAMESPACE

With autoscaling turned off, or on Community Edition, the restore command restarts the Appsmith server.

Handle failures in a pipeline

Make your pipeline stop when the restore command returns a nonzero exit status. Missing or unknown backup filenames, paths supplied as filenames, missing secrets, failed decryption, and version mismatches return exit code 1 without prompting. These checks occur before the restore stops services or changes the database. A failure during the restore itself can leave the instance partially restored.

By default, non-interactive restore stops if the backup's Appsmith version differs from the running instance. Use a matching version when possible. To deliberately proceed despite a version mismatch, add --force:

appsmithctl restore --non-interactive \
  --backup-file=appsmith-backup-TIMESTAMP.tar.gz.enc --force

--force only bypasses the version check in non-interactive mode. It does not bypass archive or secret validation, and it does not guarantee compatibility between versions. Without --non-interactive, the version confirmation prompt still appears.

Troubleshooting

If you encounter any issues during the restore process, consider the following:

• Ensure you've copied the backup archive to the correct folder within the container or pod.
• Ensure the S3 bucket has appropriate permissions to list the backup archives from the bucket.
• Verify that you are on an Appsmith paid plan and your plan is active to list backup archives from S3 bucket. For more information, see License & plans.
• Verify that you have the required permissions to execute docker-compose or kubectl commands.
• If using encrypted backups, confirm that the encryption password and salt match the original values used during backup creation.
• If restarting the pods fails, check the logs for errors. For more information, see Get Container logs guide.

If you continue to face issues, contact support using the chat widget available in the bottom-right corner of this page.