Backup and Restore

Appsmith comes with the appsmithctl command line utility. You can use the command line to interact with and manage your self-hosted instance. For example, back up and restore your Appsmith instance and database. This page provides steps to run the backup and restore commands.

How to use Appsmithctl for Docker

Usage

appsmithctl <subcommand> <options>

Subcommands

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

Subcommand	Description
--help	Shows available subcommands and how to use appsmithctl
backup	Creates a backup of the Appsmith instance
ex, export_db	Creates a backup of Appsmith internal database
--upload-to-s3	Upload the back up files to S3 bucket (Commercial Edition only)
restore	Restores the Appsmith instance from a backup
im, import_db	Restores the Appsmith internal database

Prerequisites

• The self-hosted instance should be up and running. If you haven't already installed Appsmith, refer to the Installation guides.
• Access to execute docker-compose or kubectl commands

Backup instance

You can create a backup archive of the Appsmith instance. The backup includes the database, docker.env, and Git data. Follow these steps to create a backup archive:

Docker

1. Go to the directory that has the docker-compose.yml file.

2. Create a backup archive with encryption, execute the following command:

   docker-compose exec appsmith appsmithctl backup

   The above command encrypts the backup archive with a password. When prompted, enter a password and ensure you remember it. You need this password if you ever want to restore from this backup. If you forget it, you won't be able to restore this backup. The backup archive file is stored in the /appsmith-stacks/data/backup/ folder in your container directory. You can access it at ./stacks/data/backup/ on your local machine.

3. If you can't access or have a different volume configuration, copy the archive file to your host disk with:

   # Replace the appsmith-backup-DATE_AND_TIMESTAMP.tar.gz.enc with the backup file name
   docker cp appsmith:/appsmith-stacks/data/backup/appsmith-backup-DATE_AND_TIMESTAMP.tar.gz.enc .

   After running the above command, the backup archive is copied to your current directory, indicating that the backup process is completed. You can now proceed with the remaining steps of the process you were performing.

Kubernetes

1. Get the name of the Appsmith pod with (replace the APPSMITH_NAMESPACE with your Appsmith namespace):

   kubectl get pods -n APPSMITH_NAMESPACE

2. Create a backup with encryption use the below command (replace the ANY_APPSMITH_POD_NAME with your Appsmith pod name):

   # Replace ANY_APPSMITH_POD_NAME with the name of a running Appsmith pod.
   kubectl exec ANY_APPSMITH_POD_NAME appsmithctl backup

   The above command encrypts the backup archive with a password. When prompted, enter a password and ensure you remember it. You need this password if you ever want to restore from this backup. If you forget it, you won't be able to restore this backup.

   The archive file is stored in the container directory /appsmith-stacks/data/backup/.

3. Copy the archive file using the below command, ensure that you replace the ANY_APPSMITH_POD_NAME with your Appsmith pod name, APPSMITH_BACKUP_FILENAME with your Appsmith backup filename, and APPSMITH_NAMESPACE with your Appsmith namespace:

      # Replace placeholders in capitals with appropriate values based on your deployment.
   kubectl cp ANY_APPSMITH_POD_NAME:/appsmith-stacks/data/backup/APPSMITH_BACKUP_FILENAME -n APPSMITH_NAMESPACE GIVE_NAME_FOR_COPIED_BACKUP_FILE

   After running the above command, the backup archive is copied to your current directory, indicating that the backup process is completed. You can now proceed with the remaining steps of the process you were performing.

Schedule automatic backups

Business

Docker

Follow these steps to schedule backups only for Docker Appsmith installation:

1. Go to the directory where the docker.env file is located.
2. Open the docker.env file and set the environment variable as shown below:

# Add a 5-value cron expression
APPSMITH_BACKUP_CRON_EXPRESSION="ADD_5_VALUE_CRON_EXPRESSION"

Examples

• To schedule a backup at 12:00 noon on Sunday:

APPSMITH_BACKUP_CRON_EXPRESSION="0 12 * * SUN"

• To schedule a backup daily at Midnight:

APPSMITH_BACKUP_CRON_EXPRESSION="0 0 * * *"

For more information about creating the Cron expressions, see Cron Schedule Expression Editor.

Sync backup to S3 bucket

Business

Follow these steps to sync backups with an S3 bucket for your installation type:

Docker

1. Go to the directory where the docker.env file is located.
2. Open the docker.env file and add the below entries:

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

3. Sync your backups to the S3 bucket with:

docker-compose exec appsmithctl backup --upload-to-s3

After configuration, the restore command lists local and S3 bucket backups.

Kubernetes

1. Set the Amazon S3 bucket:

   • Using the command:

   helm upgrade \
   --set applicationConfig.APPSMITH_BACKUP_S3_ACCESS_KEY=AWS_ACCESS_KEY  \
   --set applicationConfig.APPSMITH_BACKUP_S3_SECRET_KEY=<AWS_SECRET_KEY \
   --set applicationConfig.APPSMITH_BACKUP_S3_BUCKET_NAME=BUCKET_NAME  \
   --set applicationConfig.APPSMITH_BACKUP_S3_REGION=AWS_BUCKET_REGION \
     appsmith appsmith/appsmith

   • Or using values.yaml file:

     a. Update the parameter values in the values.yaml file under the applicationConfig section:

     applicationConfig:
       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

     b. Update the values:

     helm upgrade appsmith appsmith-ee/appsmith -f values.yaml

2. Get the name of the Appsmith pod with:

kubectl get pods

3. Sync your backups to the S3 bucket with:

# Replace `ANY_APPSMITH_POD_NAME` with the pod name
kubectl exec ANY_APPSMITH_POD_NAME appsmithctl backup --upload-to-s3

After configuration, the restore command lists local and S3 bucket backups.

Backup database

Follow these steps to back up your Appsmith internal database:

Attention

Ensure that the name of the backup archive (appsmith-data.archive) isn't changed.

Docker

1. Go to the directory that has the docker-compose.yml file.

2. Get your encryption details with:

docker-compose exec appsmith cat /appsmith-stacks/configuration/docker.env | grep ENCRYPTION

Keep these details handy, as you need them for restoring the Appsmith database.

3. Create a backup archive with:

docker-compose exec appsmith appsmithctl export_db

The backup archive file is stored in the /appsmith-stacks/data/backup/ folder in your container directory. You can access it at ./stacks/data/backup/ on your local machine.

4. If you can't access or have a different volume configuration, copy the archive file to your host disk with:

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

This command copies the backup archive in your current directory.

5. To recreate the same environment elsewhere, copy the docker.env file with:

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

This command copies the docker.env file in your current directory.

Kubernetes

1. Get the name of the Appsmith pod with:

kubectl get pods

2. Get your encryption details with:

# Replace `ANY_APPSMITH_POD_NAME` with the pod name
kubectl exec ANY_APPSMITH_POD_NAME -- cat /appsmith-stacks/configuration/docker.env | grep ENCRYPTION

Keep these details handy, as you need them for restoring the Appsmith database.

3. Create a database backup with:

# Replace `ANY_APPSMITH_POD_NAME` with the pod name
kubectl exec ANY_APPSMITH_POD_NAME appsmithctl export_db

The archive file is stored in the container directory /appsmith-stacks/data/backup/.

4. Copy the archive file with:

# Replace `ANY_APPSMITH_POD_NAME` with the pod name
kubectl cp ANY_APPSMITH_POD_NAME:/appsmith-stacks/data/backup/appsmith-data.archive appsmith-data.archive

Restore instance

Follow these steps to restore your Appsmith instance from a backup archive:

Docker

1. Restore your Appsmith instance with:

docker-compose exec appsmith appsmithctl restore

The command lists backup archives in the folder, with the latest backup at the bottom.

2. Select the backup archive from the given list of backup archives to restore.

Select a backup archive while restoring Appsmith instance

Attention

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

3. You can either use the existing encryption or create new values for:
   • APPSMITH_ENCRYPTION_PASSWORD
   • APPSMITH_ENCRYPTION_SALT

Option to use existing encryption values

Kubernetes

1. Get the name of the Appsmith pod with:

kubectl get pods

2. Copy the archive file to the pod with:

   • Encrypted archive file -

     # 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/

   • Unencrypted archive file -

     # Replace `ANY_APPSMITH_POD_NAME` with the pod name
     kubectl cp appsmith-backup-TIMESTAMP.tar.gz ANY_APPSMITH_POD_NAME:/appsmith-stacks/data/backup/

3. Go to the /appsmith-stacks/configuration/ folder

4. Open the docker.env file and update the below parameters:

# The one you generated and stored while creating a backup
APPSMITH_ENCRYPTION_PASSWORD=APPSMITH_ENCRYPTION_PASSWORD
APPSMITH_ENCRYPTION_SALT=APPSMITH_ENCRYPTION_SALT

5. Restore the backup with:

# Replace `ANY_APPSMITH_POD_NAME` with the pod name
kubectl exec ANY_APPSMITH_POD_NAME appsmithctl restore

6. Restart the Appsmith pods:

a. When autoscaling is turned off, or you are using a Community Edition with:

kubectl rollout restart statefulset appsmith

b. When autoscaling is turned on with:

kubectl rollout restart deployment appsmith

Restore database

Follow these steps to restore the Appsmith internal database:

Docker

1. Copy the archive file into the container with:

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

2. Import data from the backup archive file with:

docker-compose exec appsmith appsmithctl import_db

3. Copy the docker.env file with:

# Add the path for the docker.env file if not present in the installation folder
docker cp ./docker.env appsmith:/appsmith-stacks/configuration/

4. Restart the Appsmith server with:

docker-compose exec appsmith supervisorctl restart backend

Kubernetes

1. Get the name of the Appsmith pod with:

kubectl get pods

2. Copy the archive file into the container with:

# Replace `ANY_APPSMITH_POD_NAME` with the pod name
kubectl cp ./appsmith-data.archive ANY_APPSMITH_POD_NAME:/appsmith-stacks/data/restore/

3. Go to the /appsmith-stacks/configuration/ folder

4. Open the docker.env file and update the below parameters:

# The one you generated and stored while creating a backup
APPSMITH_ENCRYPTION_PASSWORD=APPSMITH_ENCRYPTION_PASSWORD
APPSMITH_ENCRYPTION_SALT=APPSMITH_ENCRYPTION_SALT

5. Import data from the archive file with:

# Replace `ANY_APPSMITH_POD_NAME` with the pod name
kubectl exec ANY_APPSMITH_POD_NAME appsmithctl import_db

6. Restart the Appsmith pods:

a. When autoscaling is turned off, or you are using a Community Edition with:

kubectl rollout restart statefulset appsmith

b. When autoscaling is turned on with:

kubectl rollout restart deployment appsmith

Troubleshooting

If you face issues, contact support@appsmith.com.