Replace /opt/mcp-gateway with ${HOME}/mcp-gateway to eliminate sudo requirements #158
Description
Summary
Replace hardcoded /opt/mcp-gateway paths with ${HOME}/mcp-gateway to eliminate the need for sudo permissions during setup and operation. The /opt directory requires root/sudo access, which creates unnecessary friction for users and potential permission issues.
Problem
Currently, the codebase uses /opt/mcp-gateway in multiple locations, which:
- Requires
sudofor directory creation and file operations - Creates ownership/permission issues between user and Docker containers
- Is not user-friendly for development and testing
- Requires additional
chownoperations to fix permissions - Goes against best practices for user-space applications
Current Occurrences
Docker Compose Files
- Lines 40-41: Registry service volumes for servers and models
- Line 44: Auth server scopes.yml volume
- Line 118: Auth server scopes.yml volume
- Line 146: Fininfo secrets volume
- Lines 164-166: Metrics service volumes
- Lines 36-37: Registry service volumes for servers and models
- Line 40: Auth server scopes.yml volume
- Line 107: Auth server scopes.yml volume
- Line 127: Fininfo secrets volume
- Lines 141-143: Metrics service volumes
Scripts
- Line 141:
MCPGATEWAY_SERVERS_DIR="/opt/mcp-gateway/servers" - Line 155: Copy JSON files comment
- Line 191:
AUTH_SERVER_DIR="/opt/mcp-gateway/auth_server"
- Line 128: Checking host scopes.yml file
Documentation
- Lines 55-57: Directory creation instructions using
sudo
- Line 379: Directory creation with
sudo mkdir - Line 383: Ownership change with
sudo chown - Line 536: Ownership fix with
sudo chown
- Lines 238-241: Directory creation and copying with
sudo
- Line 350: SystemD service WorkingDirectory (note: this uses
/opt/mcp-gateway-registrynot/opt/mcp-gateway)
servers/fininfo/README_SECRETS.md
- Line 22: Volume mount example
- Lines 30-32: Directory creation and permission setup with
sudo
Proposed Solution
Replace all instances of /opt/mcp-gateway with ${HOME}/mcp-gateway or $HOME/mcp-gateway depending on context.
Changes Required
1. Docker Compose Files
Replace volume paths:
# Before
volumes:
- /opt/mcp-gateway/servers:/app/registry/servers
- /opt/mcp-gateway/models:/app/registry/models
- /opt/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml
- /opt/mcp-gateway/secrets/fininfo/:/app/fininfo/
# After
volumes:
- ${HOME}/mcp-gateway/servers:/app/registry/servers
- ${HOME}/mcp-gateway/models:/app/registry/models
- ${HOME}/mcp-gateway/auth_server/scopes.yml:/app/auth_server/scopes.yml
- ${HOME}/mcp-gateway/secrets/fininfo/:/app/fininfo/2. Shell Scripts
Replace hardcoded paths:
# Before
MCPGATEWAY_SERVERS_DIR="/opt/mcp-gateway/servers"
AUTH_SERVER_DIR="/opt/mcp-gateway/auth_server"
# After
MCPGATEWAY_SERVERS_DIR="${HOME}/mcp-gateway/servers"
AUTH_SERVER_DIR="${HOME}/mcp-gateway/auth_server"3. Documentation
Update all setup instructions:
# Before
sudo mkdir -p /opt/mcp-gateway/{servers,auth_server,secrets}
sudo cp -r registry/servers /opt/mcp-gateway/
sudo chown -R $(whoami):$(id -gn) /opt/mcp-gateway
# After
mkdir -p ${HOME}/mcp-gateway/{servers,auth_server,secrets}
cp -r registry/servers ${HOME}/mcp-gateway/
# No chown needed!Benefits
- No sudo required: Users can set up and run without elevated permissions
- Better security: Each user has their own isolated instance
- Easier development: Developers can quickly test without permission issues
- Cross-platform: Works consistently on Linux, macOS, and WSL
- Follows best practices: User applications should live in user space
- Cleaner setup: Eliminates ownership and permission workarounds
Migration Path for Existing Users
For users who already have /opt/mcp-gateway:
# Option 1: Move existing data
sudo mv /opt/mcp-gateway ${HOME}/mcp-gateway
sudo chown -R $(whoami):$(id -gn) ${HOME}/mcp-gateway
# Option 2: Fresh install
# Simply follow new installation instructions
mkdir -p ${HOME}/mcp-gateway/{servers,auth_server,secrets}Files to Modify
-
docker-compose.yml -
docker-compose.prebuilt.yml -
build_and_run.sh -
cli/service_mgmt.sh -
docs/installation.md -
docs/macos-setup-guide.md -
docs/FAQ.md -
docs/token-refresh-service.md -
servers/fininfo/README_SECRETS.md
Acceptance Criteria
- All hardcoded
/opt/mcp-gatewayreferences replaced with${HOME}/mcp-gateway - Documentation updated to remove
sudofrom setup instructions - Scripts tested on Linux and macOS
- Docker compose files validated
- Migration guide added for existing users
- No permission-related workarounds needed