Code Backup and File Roaming

About 1061 wordsAbout 4 min

Cloud-native development environments use an on-demand approach with automatic destruction when idle. To prevent loss of uncommitted code and configuration, the system automatically performs backups and file roaming.

Workspace Code Backup

No need to worry about losing uncommitted code after the environment is destroyed — the system provides two backup methods to ensure code safety.

Tips

For team development, it is recommended to create personal branches for development. One branch is developed by only one person, which can reduce conflicts caused by code restoration.

Backup on Development Environment Destruction

After modifying code in the workspace directory /workspace, even if not committed in time, the system automatically backs it up when the environment is recycled. After rebuilding, the code is automatically restored to the workspace.

1. Backup and Restore Methods

Backup: Package uncommitted code and upload on environment destruction
Note: Each branch retains only one backup. New backups overwrite old ones. If two environments are started for the same branch simultaneously, the backup from the later destroyed environment overwrites the earlier one.
Restore: Download the backup and restore it to the workspace on environment rebuild

Tips

The following situations will not be backed up:

Individual code files or individual diff files larger than 100MB will be filtered out; only files not exceeding 100MB will be packaged
If the total backup file size exceeds 100MB, it will not be backed up

Large files are recommended to be ignored using .gitignore

2. Backup Content

Stashes in the workspace
Commits in the workspace that have not been pushed
Uncommitted code in the workspace (workspace modifications, staging area modifications, untracked files, excluding files ignored by .gitignore)

3. When Backup Code Is Deleted

Each branch retains only the latest backup; new backups overwrite old ones.
When a branch is deleted, all users' backup code under that branch is automatically cleaned up.

4. Restore Policy Description

When rebuilding or creating a new environment, it starts with the latest branch code and attempts to restore the latest backup. Conflicts may occur if code was committed outside of cloud-native development environments; in this case, the restored code can be discarded.

Tips

Workspace code backups are automatically deleted from remote storage after successful restoration, meaning each backup can only be restored once. A new backup is created when the new environment is destroyed.

Non-workspace file roaming backups (such as .gitconfig, custom roaming directories, etc.) are not deleted and will be retained for reuse across future environments.

The following content will not be backed up:

Content declared in .gitignore
Modified content in submodules
Modifications outside the workspace

Scheduled Backup Strategy

To improve backup reliability, the system also uses a scheduled backup strategy, automatically packaging and uploading uncommitted code every 5 minutes.

Download: Download the backup code package from the "My Cloud-Native Development" list page.
Deletion: The backup is deleted when you delete the development environment history record.

Tips

Files larger than 100MB will not be backed up.
Backup code packages larger than 100MB will not be backed up either.

Non-Workspace File Roaming

Workspaces supports file roaming for directories outside the workspace — roaming files are automatically restored after the environment is destroyed and a new one is created.

Maximum roaming capacity: 100 MB. Exceeding this limit will cause an error and prevent roaming.

Default Roaming Content

The following files or folders roam by user dimension and apply to all projects (~ is the current user's home directory, generally /root):

~/.gitconfig: Git global configuration. If this file already exists in the container (e.g., pre-configured in a custom environment), it is skipped during both restore and save. It's recommended to modify /etc/gitconfig instead to avoid conflicts.
~/.local/share/code-server/User/settings.json: WebIDE configuration file
~/.local/share/code-server/User/snippets/*: WebIDE related configurations
~/.local/share/code-server/User/keybindings.json: WebIDE shortcut key configuration

Users can add personal environment configuration files in the ~/.cnb directory. For example, add .env.local in ~/.cnb for personal environment variables, then use script tasks to copy or symlink it to the working directory, and add it to .gitignore.

Example 1: Copy files to the working directory

To modify the roaming config file, edit /root/.cnb/.env.local directly:

.cnb.yml
$:
  vscode:
    - name: vscode
      services:
        - vscode
      stages:
        - name: Copy .env.local file to the 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

Example 2: Symlinking files to the working directory

With symlinks, editing /workspace/.env.local in the working directory will synchronize changes to the source file:

.cnb.yml
$:
  vscode:
    - name: vscode
      services:
        - vscode
      stages:
        - name: Symlink .env.local file to the 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

Custom Roaming Directories or Files

In addition to the default roaming content above, users can also customize the directories or files to be roamed.

On the Profile > Workspaces(Open in new window) page, you can configure custom roaming directory or file paths. Once configured, these directories or files will be automatically roamed and saved when the cloud-native development environment is destroyed, and automatically restored when a new environment is created or rebuilt.

Configuration notes:

Absolute paths are required, Glob patterns are supported
Multiple paths can be separated by newlines

Examples:

/root/.bashrc
/root/.config/

Roaming Principle and Timing

Roaming timing: Modified roaming files are not immediately saved. They are extracted and persisted when the environment is destroyed.

How to restore: Roaming files are automatically restored when rebuilding the environment.

How to verify: You need to destroy the environment and recreate it to see the roaming effect.

Tips

Note:

When multiple development environments are open simultaneously, the roaming content from the later destroyed environment overwrites the earlier one
Closing the development environment using kill 1 will not successfully roam the files
If the file to be roamed is a soft link, we will roam the original file rather than the soft link, to prevent the loss of the original file. If the original file of the soft link does not exist, it will not be roamed.