Workspace Startup Customization

This guide explains how to customize your workspace environment using configuration files in your home directory and the shared project directory.

Overview

Workspaces can be customized at two levels:

• Personal customization - Files in your home directory (/home/web) that affect only your workspace
• Project-wide customization - Files in the shared directory (/shared) that affect all workspaces in the project

SSH Session Initialization

When you connect to a workspace via SSH, your shell environment is configured through several files that are sourced in sequence:

1. Shared Profile - /shared/.profile (if it exists)
2. Shared Bash Config - /shared/.bashrc (if it exists)
3. User Home Files - ~/.bashrc and ~/.workspacerc are sourced

This layered approach allows project-wide defaults to be set in /shared, which can then be overridden or extended in your personal home directory files.

Customization Methods

1. Personal Configuration Files

Files in your home directory (/home/web) allow you to customize your personal workspace environment.

~/.bashrc

Standard bash configuration file, sourced for interactive shells.

~/.workspacerc

Custom initialization file specifically for workspace customization. Sourced on session start.

~/.profile

Standard shell profile file, sourced for login shells.

2. Shared Directory Customization

The shared directory (/shared) is shared across all workspaces in a project. Files here affect everyone on the team.

Tip

Use the shared directory for project-wide conventions, tools, and configuration that should be consistent across all team members’ workspaces.

/shared/.profile

Sourced automatically on every SSH session for all users in the project.

/shared/.bashrc

Sourced for bash users on every SSH session.

/shared/bin/

This directory is automatically added to $PATH. Place executable scripts here to make them available to all workspaces.

/shared/startup.d/*.sh

Scripts in this directory run once when the workspace container starts, as your user. This is useful for initializing the workspace environment.

File Precedence and Overrides

Understanding the order in which files are sourced helps you organize your configuration:

1. /shared/.profile - Project-wide defaults
2. /shared/.bashrc - Project-wide bash configuration
3. ~/.bashrc - Personal bash configuration
4. ~/.workspacerc - Personal workspace configuration

Later files can override settings from earlier files. For example:

# /shared/.profile sets a default
export API_URL="https://api.staging.example.com"

# ~/.workspacerc can override it
export API_URL="https://api.local.example.com"

Best Practices

1. Use /shared/ for team conventions - Aliases, functions, and environment variables that everyone should use
2. Use ~/ for personal preferences - Your preferred prompt, editor, personal aliases
3. Document shared scripts - Add comments explaining what scripts in /shared/bin/ do
4. Make scripts executable - chmod +x /shared/bin/script-name
5. Use meaningful names - Name scripts and functions clearly
6. Handle errors gracefully - Check for required files/directories before using them
7. Keep it simple - Don’t over-complicate your configuration
8. Version control shared files - Consider keeping /shared/ files in a local git repository
9. Test changes - Test configuration changes before committing them for the team
10. Use comments - Document non-obvious configuration choices

Troubleshooting

Changes Not Taking Effect

After modifying shell configuration files, you need to reload them:

# Reload your shell configuration
source ~/.bashrc

# Or start a new SSH session
exit
# Then reconnect

Script Permission Denied

Make sure scripts are executable:

chmod +x /shared/bin/my-script

Conflicts Between Personal and Shared Config

If you’re experiencing unexpected behavior, check for conflicts:

# See what's defined in shared config
cat /shared/.bashrc

# See what's in your personal config
cat ~/.bashrc

# Check current environment
env | grep MY_VARIABLE

Summary

Workspace customization is available at two levels:

• Personal (/home/web): ~/.bashrc, ~/.workspacerc, ~/.profile
• Project-wide (/shared): /shared/.profile, /shared/.bashrc, /shared/bin/, /shared/startup.d/, /shared/hooks/

Use personal files for your preferences and workflow, and shared files for team-wide conventions and tools. This approach ensures consistency across the team while allowing individual customization.