docs: document non-interactive instance restores

website/docs/getting-started/setup/environment-variables.md

@@ -555,6 +555,16 @@ Controls how many recent backup archives are retained. Backups use a count-based
 
 </dd>
 
+##### `APPSMITH_BACKUP_ARCHIVE_PASSWORD`
+
+<dd>
+
+Supplies the password that `appsmithctl restore` uses to decrypt an encrypted backup archive, so the restore can run without prompting. Available from Appsmith v2.4.1. Only `appsmithctl restore` reads this variable. It has no effect on `appsmithctl backup`, which takes an encryption password from an interactive prompt and can't encrypt an archive without one. Set it only for the restore invocation, from your CI/CD secret store. Appsmith strips it from the `docker.env` it writes into a backup archive, and it isn't needed outside a restore. When it's set, Appsmith makes a single decryption attempt with it and doesn't fall back to prompting, even in interactive mode.
+
+For more information, see [Automate restores](/getting-started/setup/instance-management/backup-and-restore/restore-instance#automate-restores).
+
+</dd>
+
 <!-- vale off -->
 <br/>
 <div className="tag-wrapper">

website/docs/getting-started/setup/instance-management/appsmithctl.mdx

@@ -47,9 +47,9 @@ To create a backup of the Appsmith instance, use the following command:
   ```bash
   appsmithctl backup
   ```
-  - The `backup` command creates a backup of your Appsmith instance, including the internal database, `docker.env`, and Git data. The backup file is encrypted using a password that you provided. This password is essential for restoring the backup later, so make sure to store it securely. If the password is forgotten, the backup cannot be restored.
+  - The `backup` command creates a backup of your Appsmith instance, including the internal database, `docker.env`, and Git data. Run interactively in a terminal, it prompts for a password and encrypts the backup file with it. This password is essential for restoring the backup later, so make sure to store it securely. If the password is forgotten, the backup cannot be restored.
   - The backup file is stored in the `/appsmith-stacks/data/backup/` directory within the container. On your local machine, it is accessible at `./stacks/data/backup/`.
-  - The backup file follows the naming pattern `appsmith-backup-DATE_AND_TIMESTAMP.tar.gz.enc`.
+  - The backup file follows the naming pattern `appsmith-backup-DATE_AND_TIMESTAMP.tar.gz.enc`. Run with `--non-interactive`, or without a terminal attached, the command skips the password prompt and writes an unencrypted `appsmith-backup-DATE_AND_TIMESTAMP.tar.gz` instead.
 
 For more information about creating an Appsmith instance backup, see [Backup Instance](/getting-started/setup/instance-management/backup-and-restore/backup-instance) guide.
 </dd>
@@ -90,9 +90,10 @@ For [Appsmith paid plans](https://www.appsmith.com/pricing), backups can be uplo
   ```bash
   appsmithctl restore
   ```
-- The `restore` command restores the Appsmith instance, including the internal database, `docker.env`, and Git data, from an encrypted backup file. You will need the password used during the backup process to decrypt the backup. Without this password, the restore process will fail.
+- The `restore` command restores the Appsmith instance, including the internal database, `docker.env`, and Git data. For encrypted backups, you need the password used during the backup process to decrypt the archive.
   - The restore process assumes that the backup file is located at `/appsmith-stacks/data/backup/` within the container.
-  - The backup file should follow the naming pattern `appsmith-backup-DATE_AND_TIMESTAMP.tar.gz.enc`.
+  - The backup file should follow the naming pattern `appsmith-backup-DATE_AND_TIMESTAMP.tar.gz.enc` for encrypted archives, or `appsmith-backup-DATE_AND_TIMESTAMP.tar.gz` for unencrypted archives.
+  - From Appsmith v2.4.1, the `--backup-file`, `--non-interactive`, and `--force` options run a restore without prompts. For more information, see [Automate restores](/getting-started/setup/instance-management/backup-and-restore/restore-instance#automate-restores).
 
 For more information about restoring an Appsmith instance, see [Restore Instance](/getting-started/setup/instance-management/backup-and-restore/restore-instance) guide.
 </dd>

website/docs/getting-started/setup/instance-management/backup-and-restore/backup-instance.mdx

@@ -81,6 +81,10 @@ You can create a backup archive of your Appsmith instance, including the databas
 
 </Tabs>
 
+:::caution Unencrypted archives
+`appsmithctl backup` only asks for an encryption password when it runs interactively in a terminal. Run with `--non-interactive`, or from a pipeline or scheduled job where no terminal is attached, and it writes an unencrypted `appsmith-backup-DATE_AND_TIMESTAMP.tar.gz` instead. That archive holds a plaintext database dump, so protect it at rest and don't keep it as a pipeline artifact. Restoring it also requires the source instance's `APPSMITH_ENCRYPTION_PASSWORD` and `APPSMITH_ENCRYPTION_SALT`, which an unencrypted archive doesn't carry — save both values when you create one. For more information, see [Restore Instance](/getting-started/setup/instance-management/backup-and-restore/restore-instance#automate-restores).
+:::
+
 ## Troubleshooting
 
 If you encounter any issues during the restore process, consider the following:

website/docs/getting-started/setup/instance-management/backup-and-restore/restore-instance.mdx

@@ -91,6 +91,105 @@ Follow these steps to restore your Appsmith instance for Kubernetes-based instal
 
 </Tabs>
 
+## Automate restores
+
+Starting with Appsmith **v2.4.1**, you can run `appsmithctl restore` without prompts for automated disaster recovery or environment rebuilds:
+
+```bash
+appsmithctl restore --non-interactive --backup-file=appsmith-backup-TIMESTAMP.tar.gz.enc
+```
+
+| Option | Description |
+| --- | --- |
+| `--backup-file=<name>` | Selects an exact archive filename, including its extension. The command doesn't pick the latest backup for you. Requires `=` and a filename, not a path or an index. Checks local archives first, then S3 archives on an active paid plan with [S3 sync configured](/getting-started/setup/instance-management/backup-and-restore/sync-backup-to-s3), downloading the S3 copy only when the filename isn't already local. Also works without `--non-interactive` to skip the selection prompt. |
+| `--non-interactive` | Disables all prompts. Requires `--backup-file=<name>` and the secrets below in the restore process environment. |
+| `--force` | Continues when the backup's Appsmith version differs from the running instance. Applies only with `--non-interactive`, where a mismatch otherwise stops the restore. Interactive restores ask for confirmation instead, with or without this option. It doesn't bypass archive or secret validation, and it doesn't make the two versions compatible. |
+
+The secrets the restore process needs depend on the archive format:
+
+| Archive | Required secrets |
+| --- | --- |
+| Encrypted (`.tar.gz.enc`) | `APPSMITH_BACKUP_ARCHIVE_PASSWORD`, set to the password used when creating the archive. Appsmith restores the instance encryption keys from the archive itself. |
+| Unencrypted (`.tar.gz`) | `APPSMITH_ENCRYPTION_PASSWORD` and `APPSMITH_ENCRYPTION_SALT`, set to the values from the instance that created the backup. The archive password isn't required. |
+
+The archive password is a transient secret. Supply it from your CI/CD secret store for a single restore invocation, and never keep it in `docker.env`, Helm values, or source control. The encryption password and salt are durable instance secrets: keep them out of CI configuration and source control, but expect the restore to write them into the instance's `docker.env`, where they belong.
+
+Appsmith checks only that the encryption password and salt are present, not that they're correct. Values that don't match the source instance let the restore finish while leaving every stored datasource credential undecryptable.
+
+When `APPSMITH_BACKUP_ARCHIVE_PASSWORD` is set, Appsmith uses it for a single decryption attempt and doesn't fall back to the prompt, even in interactive mode.
+
+`appsmithctl backup` writes an unencrypted archive when it runs with `--non-interactive` or without a terminal, which is the usual case in a pipeline. An unencrypted archive holds a plaintext database dump, so protect it at rest and don't keep it as a pipeline artifact. For more information, see [Backup Instance](/getting-started/setup/instance-management/backup-and-restore/backup-instance).
+
+The following examples restore an encrypted archive that you copied to `/appsmith-stacks/data/backup/` using the steps above. Replace `TIMESTAMP` and the container or pod name with your values. For an unencrypted archive, use the `.tar.gz` filename and deliver `APPSMITH_ENCRYPTION_PASSWORD` and `APPSMITH_ENCRYPTION_SALT` the same way instead of the archive password.
+
+<Tabs queryString="current-command-type">
+
+<TabItem label="Docker" value="docker-commands">
+
+Inject `APPSMITH_BACKUP_ARCHIVE_PASSWORD` into the runner's environment, then pass the variable name, not its value, through to the container:
+
+```bash
+docker exec \
+  -e APPSMITH_BACKUP_ARCHIVE_PASSWORD \
+  appsmith appsmithctl restore \
+  --non-interactive \
+  --backup-file=appsmith-backup-TIMESTAMP.tar.gz.enc
+```
+
+Writing `-e VARIABLE` without a value sends the password in the request body instead of on a command line, so it stays out of process lists and shell history. Don't allocate a TTY (`-t`) in a pipeline. On Compose v2, replace `docker exec` with `docker compose exec -T`.
+
+</TabItem>
+
+<TabItem label="Kubernetes" value="kubernetes-commands">
+
+Deliver the password to the pod through a Kubernetes Secret. Setting it only on the machine that runs `kubectl` has no effect, and passing it on the `kubectl exec` command line writes it in plaintext to the kube-apiserver audit log, because exec arguments travel as query parameters in the request URI.
+
+1. Create a Secret holding `APPSMITH_BACKUP_ARCHIVE_PASSWORD` through your cluster's secret management. With plain `kubectl`, read the password from a file rather than from the command line, which would leave it in the runner's process list and shell history:
+
+   ```bash
+   kubectl create secret generic appsmith-restore \
+     --from-file=APPSMITH_BACKUP_ARCHIVE_PASSWORD=./archive-password
+   ```
+
+   Create `./archive-password` with mode `0600`, and delete it once the Secret exists.
+
+2. Reference the Secret from the Appsmith deployment:
+
+   ```yaml
+   envFrom:
+     - secretRef:
+         name: appsmith-restore
+   ```
+
+3. Apply the change and wait for the rollout to finish. The replacement pod doesn't carry the backup archive, so copy it now. Replace `ANY_APPSMITH_POD_NAME` with the new pod name:
+
+   ```bash
+   kubectl cp appsmith-backup-TIMESTAMP.tar.gz.enc ANY_APPSMITH_POD_NAME:/appsmith-stacks/data/backup/
+   ```
+
+4. Run the restore:
+
+   ```bash
+   kubectl exec ANY_APPSMITH_POD_NAME -- \
+     appsmithctl restore \
+     --non-interactive \
+     --backup-file=appsmith-backup-TIMESTAMP.tar.gz.enc
+   ```
+
+5. Remove the `envFrom` entry and apply again. The resulting rollout both withdraws the password and restarts the pods. Then delete the Secret, which removing the reference leaves in place:
+
+   ```bash
+   kubectl delete secret appsmith-restore
+   ```
+
+This procedure narrows the password's exposure rather than removing it. Between the rollout in step 2 and the one in step 5, `envFrom` puts the password in the environment of every process in the pod, including the running Appsmith server, and the Secret itself is readable by anyone holding `get secrets` in the namespace and stored base64-encoded in etcd unless the cluster encrypts secrets at rest. Because an encrypted archive carries the instance encryption keys, this password ultimately protects every stored datasource credential, so rotate it after the restore.
+
+</TabItem>
+
+</Tabs>
+
+Make your pipeline stop when `appsmithctl restore` returns a nonzero exit status. In non-interactive mode, unknown filenames, paths supplied as filenames, missing secrets, failed decryption, and version mismatches all exit with status `1` before the command stops services or changes the database. A failure during the restore itself can leave the instance partially restored.
+
 ## Troubleshooting
 
 If you encounter any issues during the restore process, consider the following:
@@ -99,7 +198,7 @@ If you encounter any issues during the restore process, consider the following:
 - Ensure the S3 bucket has appropriate permissions to list the backup archives from the bucket.
 - Verify that you are on an [Appsmith paid plan](https://www.appsmith.com/pricing) and your plan is active to list backup archives from S3 bucket. For more information, see [License & plans](/getting-started/setup/instance-configuration/admin-settings#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 restoring an unencrypted archive, confirm that `APPSMITH_ENCRYPTION_PASSWORD` and `APPSMITH_ENCRYPTION_SALT` match the values from the instance that created the backup. An encrypted archive carries these values, so it needs only the archive password.
 - If restarting the pods fails, check the logs for errors. For more information, see [Get Container logs](/getting-started/setup/instance-management/how-to-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.
+If you continue to face issues, contact support using the chat widget available in the bottom-right corner of this page.