Here, to summarize, we provide a checklist for key points in setting up
Templates to standardize dev environments for your team on Crafting. Depending on your specific need, you don't necessarily need to have everything in this list, but it's good to check them to find opportunities for optimizing the dev experience.
- Setup workspaces with automated source code checkout (instructions here)
- Setup libraries and packages needed by the source code, and persist them in snapshots (instructions here and here )
- Setup automated build and service launch in workspaces in Repo Manifest (instructions here)
- If needed, setup environment variables and initialization scripts to further customize the workspace (instructions here and here)
- Setup dependency services and custom containers to run together with your workspaces, and automate the loading of test dataset (instructions here)
- Setup endpoints for external access to the services running in sandbox (instructions here)
- If needed, setup resources to represent cloud resources or Kubernetes namespaces (instructions here, here, and here)
- If needed, setup
secretsto manage development credentials (see here)
- If needed, setup an instruction in mark-down for your team talking about how they can use the sandbox (see here)
In the remainder of this page, we will discuss some best practices for using templates:
- Best practice for managing the templates
- Best practice for snapshots
For any non-trivial templates, we strongly recommend storing them in source repositories and manage them "config-as-code" in the YAML format. Crafting allows editing the template directly in the YAML format so that pasting an existing YAML config into a template for testing its validity is straightforward. See Sandbox Definition for the details in how to define a template.
Crafting does not require any particular way to store them but the following practices are good candidates:
- If your code is mono-repo or you have a "main" repo, you could store the template somewhere in there, or
- If you have a separate "dev ops" repo where you store a long of shared configurations, you could store the template there as well, or
- you can create a separate repo just for storing the template.
Given it is more convenient to edit and test template directly on Crafting web console, it's reasonable to iterate quickly without storing it at first for setting up something new. But once it gets to a good shape, it's best practice to store the YAML definition somewhere and enforce a process for updating it.
In addition, the template depends heavily on Repo Manifests to automate build and launch services from the source code. As the name suggests, it's corresponding to a single repo, so naturally we recommend to store them in their corresponding repo. Even though you can directly define them as part of the template, we strongly recommend they are store in the
.sandbox/manifest.yaml under the repo for long term maintenance.
In summary there are four types of snapshots:
- Base snapshot: taken from a workspace root filesystem, with home directory (
/home) excluded; (see Setup workspaces)
- Home snapshot: taken from the home directory of a workspace owner (
/home/owner) using the include/exclude list explicitly; (see Setup workspaces)
- Dependency/Container snapshot: taken from the data directory of a dependency service, or a persistent volume mounted on container; (see )
- Personal snapshot: a snapshot containing personalized configurations and can be applied to the home directory (
/home/owner) for every workspace in newly created sandboxes. (see Personalize your sandbox)
To have a more reproducible and manageable process to track what's inside each snapshot, we recommend using a script to create them. In the script, you can run things like
sudo apt install, etc. to install the things needed. And the script should be checked-in as code for source control.
When an update of snapshot is needed, instead of just adding the packages and re-take the snapshot, you can:
- Create a workspace without the snapshot;
- Run the updated scripts (store in source repo with code review) to set files
- Re-create the snapshot
All snapshots share the same namespace regardless of the type. It's recommend prefixing the snapshot type in the name to avoid conflicts, for example:
- Base Snapshots are named as
- Home Snapshots are named as
- Dependency Snapshots are named as
NAME will be defined based on the purpose of the Snapshot, and
REV can be anything indicating a revision, for example a date in the format of
YYYYMMDD or a monotonic version number etc.
If there are multiple sub-teams or sub-projects, a prefix can be added, e.g.
Snapshots created for personal use can prefix the user name, e.g.
It's helpful to put VS Code settings and extensions in snapshots (home or personal). The system supports VS Code web (in the browser) or desktop VS Code connecting over SSH. And they are using different folders for the settings and extensions. Here's the base folder of different VS Code editions:
- VS Code used in Web IDE:
- Microsoft VS Code Desktop:
- Open Source VS Code Desktop:
The following subfolders (or files) contain useful configurations that can be put in a snapshot:
extensions: all installed extensions, so the whole folder can be included in a snapshot;
data/Machine/settings.json: the per-machine settings. It can be included in a personal snapshot.
Updated 10 months ago