Basic and custom distribution packages
Create a custom Setapp distribution package
Distribute Setapp for Teams using MDM
About MDM
MDM (Mobile Device Management) is a solution for system administrators that allows them to manage Apple software on Macs, iPads, iPhones, and Apple TVs.
There are many different MDMs in the market: Jamf, Mosyle, etc. You can use any of them — Setapp for Teams is compatible with all.
With Setapp for Teams, you can use MDM to:
- Remotely install Setapp on the Macs that belong to the members of your team.
- Apply and update the same Setapp configuration on every computer quickly and easily.
Using MDM distribution saves time since your team members don't spend time setting up Setapp on their Macs. Instead, a single person, an MDM distribution specialist, installs and configures Setapp for the entire team.
To start distributing Setapp for Teams using MDM, you'll need:
- A distribution package that contains the Setapp desktop app and the config YAML file with your team settings.
- Jamf installation policy for the distribution package.
Basic and custom distribution packages
In this document, we mention 2 types of distribution packages. Let's discuss them.
The basic package is provided by the Setapp development team and is used as a basis (or template) for building a custom Setapp package for MDM distribution.
The basic package is a writable DMG image that consists of:
- Setapp desktop app (
Setapp.app
) - Config file template (
team_config.template.yml
)
We made the basic package for the convenience of MDM specialists. Its advantage is the writable format that allows saving changes in the config file and then building a custom package right away using Disk Utility; no extra operations are involved.
The custom package is created from the basic package manually by an MDM specialist. You'll find the detailed steps in the section below.
The difference between packages is that the custom one contains the modified config file with the actual team settings, whereas the basic image has a config file template with no real settings specified. These settings are discussed in this section.
Create a custom Setapp distribution package
Required accounts
Before you start, ensure you have the following accounts:
- Active team owner Setapp account.
To create a custom package, you'll need a basic Setapp package and your team key. These resources are available on the "Jamf distribution" page of your online Setapp account. To access the page, you must have a team owner account in Setapp for Teams. If you don't have an account, you can ask the actual Setapp team owner in your company to download the resources and share them with you.
Note: Historically, the MDM page in Setapp is called "Jamf distribution," which is suitable for all the MDM. Please don't be confused with the naming. - MDM account.
- Apple Developer account.
Step 1: Download the basic Setapp package
Go to the "Jamf distribution" page of your online Setapp for Teams account and click Download DMG.
Step 2: Specify team settings in the config file
Using the config YAML file, you can apply the same settings for the Setapp desktop app on all Macs in your team. Here's what these settings allow you to do:
- Restrict access to some apps from the Setapp suite for the members of your team. See the "Forbidden apps" section for details.
- Allow new team members to register their Setapp accounts using the Setapp desktop app. In this case, Setapp team owners don't have to send personal invites to new members. See the "Add and remove members in a team" article for details.
The config file template is a part of the basic Setapp package, it is stored in the following location:
/SetappDistribution/Users/username/Library/Application Support/Setapp/Config/team_config.template.yml
The template name is team_config.template.yml
. To make the file active for the Setapp application in your custom package, you must rename it team_config.yaml
(remove ".template" from the title).
Edit the config file. To access the config file, mount the basic Setapp package using Disk Utility or other similar applications.
You can use any plain text editor or IDE for editing. Since the basic Setapp package is writable, you can edit and save the config file directly in its location (the Config
directory).
When using Disk Utility, you might see a warning after saving changes in the config file. The dialog informs that the mounted volume is too small to support permanent version storage, and the older versions of the file will not be available. Since the previous file versions are not needed for distributing Setapp via MDM, you can ignore the warning and continue working with the distribution package.
The sections below discuss the settings in the config file.
Company name
The company_name
key-value pair specifies the organization name that is displayed for team members in the Setapp desktop app. The value may contain several words; quotation marks are not required. For example:
company_name: Setapp for Teams
Team key
The team_key
key-value pair contains the unique team identifier.
With Jamf, new members can create a Setapp account and join a team without personal invites, using only Setapp on their Macs. To make this happen, you’ll need the team key like this:
team_key: RGTex9Jia7xxxx8sjpRdkF9Uxu9N0veX
For more details on the process from the team owner's perspective, see "Add team members using Jamf."
The config file template comes with a placeholder that must be manually replaced with a valid key generated for your team. You can get the key on the "Jamf distribution" page of the online Setapp account.
Replace the team key. To issue a new key, go to the "Jamf distribution" page and click "Reissue key."
If a team key has been reissued, it must be replaced in the config file — otherwise, the new team members won't be able to create new Setapp accounts. After replacing the key, you will need to build a new custom Setapp package and distribute it among all the members of your Setapp team.
Forbidden apps
The forbidden_apps
key-value pair specifies the apps you don’t want your team members to install. For example, if you have a company policy of avoiding torrents, you can specify such applications using forbidden_apps
; as a result, the torrent apps won’t be displayed in the Setapp desktop application, so your teammates won't be able to install them.
An item in the forbidden_apps
key-value pair consists of an app identifier followed by a comment with the app name (for human readability).
The config file template contains all the apps available in Setapp. By default, every app item is commented (has the "#" symbol at the beginning of the line), which means all apps are allowed. To forbid an app, uncomment the corresponding line (remove the first "#" symbol), like in the example below:
forbidden_apps: - 263 # CleanMyMac X
Step 3: Build your custom Setapp distribution package
We need this step to ensure the config file with your team settings has been successfully saved as a part of your custom package. In this section, we're providing instructions for the Disk Utility app. However, you can use other methods and tools — for example, the Jamf Composer app.
The custom package must use the DMG format, not PKG. With DMG, during the distribution process, the Setapp config file is placed in the corresponding user's directory. A separate folder with the name of the MDM distribution specialist is not created for the config file.
To build a package using Disk Utility, follow these steps:
- Ensure that the basic Setapp package (
SetappDistribution.dmg
) has been mounted, and the config file in the package contains your team settings. - Start the Disk Utility app.
- Choose File > New Image > Image from "SetappDistribution."
Alternatively, control-click the SetappDistribution image in the sidebar and choose Image from "SetappDistribution." - Enter a filename for your new disk image, add tags if necessary, then choose where to save it.
- Click the Format pop-up menu and choose "read-only."
- Don't encrypt the package.
- Click Save, then click Done.
You can use the resulting DMG image as your custom Setapp distribution package.
Step 4: Sign the package with a Developer ID certificate
This is a common procedure, covered in these Apple developer articles:
- "Sign a Mac Installer Package with a Developer ID certificate."
- "Notarizing Your App Before Distribution."
That's it! After signing, your Setapp for Teams package is ready to be distributed using MDM.
Distribute Setapp for Teams using MDM
You can use any MDM you want. In this section, we'll show how to configure Jamf just as an example.
Jamf
Setapp for Teams can be distributed with Jamf as a common macOS application; it doesn't require special permissions or flows. Use the "Software Distribution" section of the Jamf Pro Administrator's Guide as a reference.
To create a Jamf installation policy, see "Managing Policies" in the Jamf Pro Administrator's Guide. When specifying the policy options, choose "Fill existing user home directories (FEU)" and make sure the "Fill user templates (FUT)" option is not selected.
Comments
0 comments
Please sign in to leave a comment.