Keep files in a Shared Folder

A package can keep its files in a DSM Shared Folder instead of its private data folder. You declare the folder in dsm-package.yaml. The installation wizard either asks the administrator to pick an existing Shared Folder (select) or creates one for you (create). Your app then reads the folder name from a file the installer writes.

Set it up

Create a project with a folder, or add the block to an existing dsm-package.yaml:

synopkgland init -t native-go --shared-folder select my-app

Option	Meaning
`--shared-folder select\|create`	The mode.
`--shared-folder-name <name>`	The Shared Folder to create. Only for `create`.
`--shared-folder-key <key>`	The key your app uses. Default `shared`.
`--shared-folder-permission ro\|rw`	The access the package account gets. Default `rw`.

The same declaration in dsm-package.yaml:

install:
  sharedFolder:
    # select or create
    mode: select
    # the name your app reads the folder by
    key: media
    # ro or rw: the access the package account needs
    permission: rw
    # create only: the Shared Folder to create
    # name: my-app-data

Field	Rule
`mode`	`select` or `create`
`key`	`^[a-z][a-z0-9_]{0,31}$`. It must not start with `pkgwizard_`, `synopkg` or `change_`.
`permission`	`ro` or `rw`
`name`	Required for `create`, not allowed for `select`. `^[A-Za-z0-9][A-Za-z0-9_-]{0,31}$`. DSM system names such as `homes`, `users`, `volume1` and `usbshare1` are refused.

install accepts only sharedFolder. A project declares one Shared Folder.

What the installer shows

Mode	Install wizard	Upgrade wizard
`select`	A step with a list of the NAS’s Shared Folders and a note about permissions.	The current folder is kept unless the administrator checks the change box.
`create`	A note that the package creates the folder `name` and gives the package account the permission. If the folder already exists, it is kept and only the package account’s permission is set.	The same note.

With select, DSM does not give the package account access to a folder chosen in the wizard. After the install, an administrator opens Control Panel > Shared Folder, edits the folder, and under Permissions > System internal user gives the package account ro or rw. The package account has the same name as the package. Until then your app reports the folder as not readable.

With create, uninstalling the package never deletes the Shared Folder or its files.

Use it

The installer writes config.json in the app’s data folder. It stores the name of the folder, not its path:

{"schema":1,"shared_folders":{"media":"my-share"}}

The Go template resolves the volume path every time, so a folder that moves to another volume keeps working. Read it with Config.SharedFolders(), or with app.ReadSharedFolders and app.ResolveSharedFolder. Each folder reports key, name, path, exists, readable and writable. The permission check follows the DSM ACL. The template includes the same list in the app.status answer as shared_folders. If config.json is damaged, app.status reports shared_folders_error.

app.status is available to administrators by default. To show it to every signed-in user, set "app.status": "authenticated" in backend/internal/api/permissions.json.

Limits

Limit	Value
Declarations per package	1
Key	1 to 32 characters
Created folder name	1 to 32 characters
`init --shared-folder`	`native-go` template only
Permission for the package account	`ro` or `rw`

Troubleshooting

Symptom or code	Cause	Fix
`STANDALONE_SHARED_FOLDER_INVALID`	A field breaks a rule in the tables above.	Fix `install.sharedFolder`.
`INIT_SHARED_FOLDER_INVALID`	`init --shared-folder` got an invalid value, or the template is not `native-go`.	Fix the option, and use `-t native-go`.
`readable` or `writable` is `false`	The package account has no access to the chosen folder.	In Control Panel > Shared Folder, give the package account `ro` or `rw`.
`exists` is `false` with `shared folder not found on any volume`	No volume has a folder with that name.	Check that the folder still exists.
The error says the name matches more than one volume	Two volumes each have a folder with that name.	Rename one folder.

See Errors for every code.