Motivation

When using python -m localstack.dev.run, local code checkouts if present are mounted into the container. This may cause confusion if the local project checkout is old and incompatible with the version of LocalStack in the container.

In particular, we rely heavily on our fork of moto which changes semi-frequently. This can cause semi-regular breakages which are difficult to debug.

I think mounting non-core packages should be opt-in to reduce surprises, and should be straightforward and self-documenting to help discoverability.

Changes

• Add new argument -l/--local-packages which can be used to specify which packages are mounted (if found)
• Define which packages are available in a declarative way so additional packages can be easier to add in the future
• Ensure the help string includes the list of packages which can be mounted, as well as validating the user's input to ensure only valid packages can be specified
• Update the example docstring

Testing

• Check out rolo and moto in the same parent directory as localstack is checked out in, making the following structure:

somedir
├── localstack
│   ├── ...
│   ├── localstack-core
│   │   ├── localstack               <- will be mounted into the container
│   │   └── localstack_core.egg-info
│   ├── pyproject.toml
│   ├── tests
│   └── ...
├── moto
│   ├── AUTHORS.md
│   ├── ...
│   ├── moto                         <- will be mounted into the container
│   ├── moto_ext.egg-info
│   ├── pyproject.toml
│   ├── tests
│   └── ...
├── rolo
│   ├── AUTHORS.md
│   ├── ...
│   ├── moto                         <- will be mounted into the container
│   ├── moto_ext.egg-info
│   ├── pyproject.toml
│   ├── tests
│   └── ...

• On master, run python -m localstack.dev.run and note the shown configuration posted at the start of the command contains rolo and moto, e.g. in the following example see the volumes section contains both localstack/moto/moto and localstack/rolo/rolo

{
    'image_name': 'localstack/localstack',
    'name': 'localstack-main',
    'volumes': [
        '/Users/simon/work/localstack/localstack/localstack-core/.filesystem/var/lib/localstack/cache/machine.json:/var/lib/localstack/cache/machine.json:ro',
        '/Users/simon/Library/Caches/localstack/volume:/var/lib/localstack',
        '/var/run/docker.sock:/var/run/docker.sock',
        '/Users/simon/work/localstack/localstack/localstack-core/localstack:/opt/code/localstack/localstack-core/localstack',
        '/Users/simon/work/localstack/moto/moto:/opt/code/localstack/.venv/lib/python3.11/site-packages/moto:ro',
        '/Users/simon/work/localstack/rolo/rolo:/opt/code/localstack/.venv/lib/python3.11/site-packages/rolo:ro',
        '/Users/simon/work/localstack/localstack/bin/docker-entrypoint.sh:/usr/local/bin/docker-entrypoint.sh:ro'
    ],
    'ports': ['0.0.0.0:4566:4566', '0.0.0.0:443:443', '0.0.0.0:4510-4560:4510-4560'],
    'exposed_ports': [],
    'env_vars': {
        'GATEWAY_LISTEN': '0.0.0.0:4566,0.0.0.0:443',
        'EXTERNAL_SERVICE_PORTS_START': 4510,
        'EXTERNAL_SERVICE_PORTS_END': 4560,
        'DNS_ADDRESS': '127.0.0.1',
        'DEBUG': '1',
        'LOCALSTACK_ROOT_DIR': '/Users/simon/work/localstack',
        'DISABLE_EVENTS': '1',
        'GATEWAY_SERVER': 'twisted',
        'DOCKER_HOST': 'unix:///var/run/docker.sock',
        'IMAGE_NAME': 'localstack/localstack'
    },
    'privileged': False,
    'remove': True,
    'interactive': True,
    'tty': True,
    'detach': False
}

• Check out this PR and run the same command and note that the two directories are not present
• Run python -m localstack.dev.run -l rolo and note that rolo is mounted, but moto is not
• Try further combinations