Workspace Startup Customization

Workspace customization falls into two categories:

• Environment startup — Scripts that run when the workspace environment starts, before any user connects
• Shell session — Configuration that applies each time you open an SSH session

Within each category, customization can be project-wide (in /shared/, affecting all workspaces) or personal (in /home/web/, affecting only your workspace).

Environment Startup

Startup scripts run once when the workspace environment starts. Use these for tasks like installing dependencies, seeding data, or configuring services.

No Login Shell

Startup scripts run as the web user but not in a login shell. Environment variable customizations from .bashrc, .profile, or other session files are not available. If your script needs specific $PATH entries or environment variables, set them explicitly within the script.

Project-Wide: /shared/startup.d/*.sh

Scripts here run on every workspace in the project. Use this for team-wide initialization — setting up shared tools, populating config files, or running migrations.

/shared/startup.d/01_setup-env.sh

#!/bin/bash
cp /shared/config/env.template /home/web/html/.env

Personal: ~/startup.d/*.sh

Scripts in /home/web/startup.d/ run after the shared startup scripts. Use this for personal workspace initialization that shouldn’t affect teammates.

~/startup.d/01_my-setup.sh

#!/bin/bash
ln -sf /shared/media /home/web/html/pub/media

Execution Order

1. /shared/startup.d/*.sh — Project-wide
2. ~/startup.d/*.sh — Personal

Within each directory, scripts run in alphabetical order. Name them with numeric prefixes (e.g., 01_, 02_) to control ordering.

Shell Session

Shell session files are sourced each time you connect via SSH. Use these for environment variables, aliases, prompt customization, and $PATH modifications.

Project-Wide

/shared/.profile

Sourced on every SSH session for all workspaces in the project. Set project-wide environment variables and defaults here.

/shared/.profile

export APP_ENV="development"
export COMPOSER_MEMORY_LIMIT=-1

/shared/.bashrc

Sourced for bash sessions. Define project-wide aliases and functions here.

/shared/.bashrc

alias mage='php bin/magento'
alias cc='php bin/magento cache:flush'

/shared/bin/

Automatically added to $PATH. Place executable scripts here to make them available as commands in all workspaces.

chmod +x /shared/bin/my-script
# Now available as: my-script

Personal

~/.bashrc

Standard bash configuration. Personal aliases, functions, and environment variables.

~/.workspacerc

Workspace-specific personal configuration, sourced on session start.

~/.profile

Standard shell profile, sourced for login shells.

Source Order

Shell files are sourced in this sequence:

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

Later files can override earlier ones:

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

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

Best Practices

• Make scripts executable — chmod +x on anything in startup.d/ or /shared/bin/
• Use numeric prefixes — 01_, 02_ to control execution order in startup.d/
• Document shared scripts — Add comments explaining what scripts do
• Version control /shared/ — Consider keeping shared files in a local git repository
• Test before committing — Verify startup scripts work before pushing to the team

Troubleshooting

Shell changes not taking effect

Reload your config or start a new session:

source ~/.bashrc
# Or disconnect and reconnect

Startup script permission denied

chmod +x /shared/startup.d/my-script.sh
chmod +x ~/startup.d/my-script.sh

Conflicts between shared and personal config

# Check what's set in shared config
cat /shared/.bashrc

# Check personal config
cat ~/.bashrc

# Inspect a variable
env | grep MY_VARIABLE

Summary

Type	Project-Wide (/shared/)	Personal (~/)
Environment startup	/shared/startup.d/*.sh	~/startup.d/*.sh
Shell session	/shared/.profile, /shared/.bashrc, /shared/bin/	~/.bashrc, ~/.workspacerc, ~/.profile