Attach storage and find your files
What happens to the persistent volume?
The service and destination path you select identify the persistent volume being replaced. The path inside the app stays the same; its storage source changes.
| Stage | Where the app reads and writes | What happens to the other copy |
|---|---|---|
| Before attachment | The original volume on the app host | No attached App Storage volume is in use at this path. |
| During attachment | The app is stopped while the panel copies and verifies its files | The original local volume is retained. |
| After attachment | The App Storage volume on the storage server, mounted at the same path | The original local copy is no longer updated by this app path. |
| After detachment | The original local volume again | Newer files and changes remain on the detached App Storage volume; they are not copied back. |
Example: website files and a database
Suppose an app has one persistent volume for website uploads and another for its database. Attaching App Storage to the uploads path moves only the uploads. The database continues using its existing volume unless you separately attach a qualified database path.
If you upload a new photo after attachment, it is written to App Storage. Detaching later switches the app back to the original local copy, which does not contain that photo. The photo remains on App Storage, but the app no longer reads that volume at this path.
An attachment does not move the app's CPU or memory to the storage server, merge local and remote capacity, or automatically remove the original local volume. See detaching safely before switching back.
Before attaching
- Open the app and stop it. Confirm its status is Stopped.
- Return to Storage → App Storage and find an available volume.
- In Attach to a stopped app, check the app name, service and destination path.
Only qualified app versions, services and paths appear. The app must be on a supported Dallas host. An app missing from the list is not permission to enter a custom mount path elsewhere: see compatibility and troubleshooting.
Attach and wait
Select Attach storage. The panel copies and verifies the existing local files before changing the app's storage mapping. File access may pause during this handover. Do not start the app or retry unrelated storage operations while the attachment is pending.
Wait for the volume to show Attached, then start the app from its app page. Check the application itself: open the site, load a sample file or confirm its normal health check. For a database service, verify through the app or its database tools.
Where to upload files
Open the app's Files tab and connect using its displayed SFTP details. The app's existing file folders stay the entry point. A file path inside the container can differ from its SFTP folder: for example, a website path such as /usr/share/nginx/html can be presented as /data in SFTP.
Use the path shown for that app. Nginx may expose /data and /config; Navidrome exposes its music library at /music. Upload to the actual listed folder rather than assuming every volume lives in /data.
Multiple volumes
Allocate a separate volume for each supported service/path you want to move. A pool can serve several apps, but one volume is not a shared folder simultaneously mounted by unrelated apps. Each attachment retains its own app and path assignment. All volumes in the pool share the pool's monthly transfer allowance.
App updates
The attachment belongs to the persistent storage path rather than the replaceable app container. A qualified normal app update keeps that mapping. Check compatibility before changing recipes, service layouts or app versions outside the supported update path, and verify the app after an update.