Workspaces environments are designed for on-demand use with automatic destruction when idle.

To prevent the loss of uncommitted code and configuration files when the development environment is destroyed, Workspaces implements the following file roaming strategy:

Uncommitted Code in Workspace

After modifying code in the current workspace directory /workspaces, there's no need to worry about losing modification records if you haven't committed them in time. When the environment is recycled, the modified code will be backed up remotely. After rebuilding the development environment, uncommitted code will be restored to the workspace.

1. Backup and Restoration Method

• Backup when environment is destroyed: Uncommitted code is backed up using git stash to an invisible remote branch, utilizing the repository's storage capability.
• Restore when environment is rebuilt: Backup code from the invisible remote branch is restored to the workspace using git stash pop.

Note: Large files in the workspace may cause backup failure. Try to avoid storing large files like installation packages over 1GB in the workspace.

1. Restoration Strategy

• Rebuilding environment after destruction: Restores backup code from the original environment.
• Starting development environment on a branch: Restores the latest backup code for that branch.

Note: After code restoration, the backup in the invisible remote branch will be deleted, meaning each backup can only be restored once. New backup code will be created when the new environment is destroyed.

Tips

Content declared in .gitignore will not be backed up

Scheduled Backup Strategy

To avoid timing issues with the above backup strategy, Workspaces also implements a scheduled backup strategy, periodically packaging and uploading uncommitted code locally.

• Backup method: Captures uncommitted code from workspace every 5 minutes and creates a compressed package for upload.
• Download method: Backup code packages can be downloaded from the My Workspaces list page.

Note:

• Files over 100MB will not be backed up.
• Backup code packages over 100MB will not be backed up.

Non-Workspace Files

Remote development supports file roaming for certain directories outside the workspace.

After environment destruction and recreation, roamed files can be restored to the development environment.

Maximum roaming capacity: 64MB, exceeding this limit will result in an error and prevent roaming.

Roaming Content

The following files or folders will roam by user dimension, effective for all projects (~: current user's home directory, usually /root):

• ~/.gitconfig: git global configuration file
• ~/.local/share/code-server/User/settings.json: WebIDE configuration file
• ~/.local/share/code-server/User/snippets/*: VSCode related configurations
• ~/.cnb: Users can add personal environment configuration files as needed in this directory.

Instructions for using the ~/.cnb directory:

• Adding configuration files: If a repository needs to add a personal configuration file .env.local for storing personal environment variables, you can add the .env.local file in the ~/.cnb directory
• After environment startup, you can configure script tasks to copy or symlink ~/.cnb/.env.local to the working directory (default is /workspace), configure .cnb.yml as follows
• Add ignored file .env.local in .gitignore to prevent personal configuration files from being committed to the repository

1. Example one, copy file to working directory:

To modify roaming configuration files, you need to directly modify /root/.cnb/.env.local

# .cnb.yml
$:
  vscode:
    - name: vscode
      services:
        - vscode
      stages:
        - name: Copy .env.local file to working directory (repository root)
          # ./ is the working directory, default is /workspace
          script: |
            if [ -e "/root/.cnb/.env.local" ]; then
                cp -f /root/.cnb/.env.local ./
            else
                echo "File does not exist"
            fi

1. Example two, symlink file to working directory:

To modify roaming configuration files, you can modify /workspace/.env.local in the working directory (symlink method will sync changes to source file)

# .cnb.yml
$:
  vscode:
    - name: vscode
      services:
        - vscode
      stages:
        - name: Symlink .env.local file to working directory (repository root)
          # ./ is the working directory, default is /workspace
          script: |
            if [ -e "/root/.cnb/.env.local" ]; then
                ln -sf /root/.cnb/.env.local ./.env.local 
            else
                echo "File does not exist"
            fi

Roaming Principle and Timing

Roaming timing:

When users modify configurations (like settings.json) in the development environment, the changes are not roamed immediately. Instead, when the development environment is destroyed, the files that need to be roamed are extracted and persistently stored.

How to restore roamed files:

When rebuilding the development environment, roamed files will be automatically restored.

How to verify if file roaming was successful:

After modifying roamable files, to verify the changes, you need to wait until the development environment is destroyed and then create/rebuild the environment to see the roaming effect of the modified files.