Skip to content

Support mounting volumes and init hooks via config#332

Open
anisaoshafi wants to merge 4 commits into
mainfrom
devx-925-support-volumes-in-lstk
Open

Support mounting volumes and init hooks via config#332
anisaoshafi wants to merge 4 commits into
mainfrom
devx-925-support-volumes-in-lstk

Conversation

@anisaoshafi

@anisaoshafi anisaoshafi commented Jun 19, 2026

Copy link
Copy Markdown
Collaborator

Closes DEVX-925.

Adds a per-container volumes list to config.toml for arbitrary bind mounts. The main use case being Snowflake init hooks (scripts mounted into /etc/localstack/init/ready.d/ that run on startup).

[[containers]]
type = "snowflake"
port = "4566"
volumes = ["./init.sf.sql:/etc/localstack/init/ready.d/init.sf.sql"]
  • Docker-style "host:container[:ro]" specs.
  • Relative sources resolve against the config file's directory; ~/ is expanded (the Docker SDK treats a non-absolute source as a named volume, so this is required). Windows drive-letter sources (C:\...) are handled.
  • Extra mounts must already exist (init-hook entries are files); only the persistence dir is auto-created.

volume vs volumes

The singular volume and the plural volumes are not general synonyms; they overlap only for the persistence directory:

  • volume only sets the persistent-state dir, always mounted to /var/lib/localstack (the dir managed by lstk volume path / lstk volume clear).
  • volumes is a superset: it can mount arbitrary paths and set the persistence dir, via the entry whose container target is /var/lib/localstack.

So these are equivalent for persistence:

volume  = "/data"
# same persistence mount as
volumes = ["/data:/var/lib/localstack"]

Differences to keep in mind:

  • volume cannot express init hooks or any non-persistence mount — use volumes.
  • A volumes source is path-resolved (relative → config dir, ~/ expanded); the legacy volume value is used verbatim, so prefer an absolute path there.
  • Declaring the persistence dir in both volume and a volumes entry with different sources is a configuration error; the same source in both is allowed.

volume stays supported for backward compatibility so existing config.toml don't break.

@anisaoshafi anisaoshafi added semver: patch docs: skip Pull request does not require documentation changes labels Jun 19, 2026
@anisaoshafi anisaoshafi force-pushed the devx-925-support-volumes-in-lstk branch 4 times, most recently from d367c1f to 0d7b899 Compare June 25, 2026 10:35
anisaoshafi and others added 2 commits June 25, 2026 12:41
Add a per-container `volumes` list of Docker-style "host:container[:ro]"
bind specs, enabling arbitrary mounts such as Snowflake init hooks
(e.g. /etc/localstack/init/ready.d/). The persistence mount to
/var/lib/localstack is folded into this list; the legacy singular
`volume` field still works for backward compatibility.

Relative host sources resolve against the config file's directory and a
leading ~/ is expanded, since the Docker SDK treats a non-absolute
source as a named volume. Extra mounts must already exist (init-hook
entries are files), unlike the persistence dir which is created.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two Windows-only bugs broke `volumes` parsing:

- The container target was validated with filepath.IsAbs, which rejects
  "/var/lib/localstack" on Windows (no drive). The target is always a Unix
  path inside the container, so validate it with path.IsAbs (slash semantics).
- A Windows host source has a drive letter ("C:\\data"), whose ':' was
  mistaken for the host:container separator. Add a drive-letter-aware
  splitter, guarded to Windows so a single-letter relative host dir
  ("a:/data") stays valid elsewhere, matching Docker's behavior.

Make the volume unit tests OS-portable by using filepath-based absolute
sources instead of hardcoded Unix paths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@anisaoshafi anisaoshafi force-pushed the devx-925-support-volumes-in-lstk branch from 0d7b899 to 145923a Compare June 25, 2026 10:52
anisaoshafi and others added 2 commits June 25, 2026 13:07
Clarify in the README and CLAUDE.md that the singular `volume` and plural
`volumes` overlap only for the persistence mount: `volume` only sets the
/var/lib/localstack dir and is used verbatim, while `volumes` is a superset
that also handles arbitrary mounts (init hooks) and resolves relative/~ paths.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@anisaoshafi anisaoshafi marked this pull request as ready for review June 25, 2026 11:26
@anisaoshafi anisaoshafi requested a review from a team as a code owner June 25, 2026 11:26
@anisaoshafi

Copy link
Copy Markdown
Collaborator Author

@mmaureenliu would you like to give it a try and see how this works for snowflake? In my test it works, but wanted to double check I'm doing the right thing. Any feedback is welcome!

@mmaureenliu

Copy link
Copy Markdown

@mmaureenliu would you like to give it a try and see how this works for snowflake? In my test it works, but wanted to double check I'm doing the right thing. Any feedback is welcome!

Do I just build from this branch and run it with snowflake?

@anisaoshafi

Copy link
Copy Markdown
Collaborator Author

@mmaureenliu would you like to give it a try and see how this works for snowflake? In my test it works, but wanted to double check I'm doing the right thing. Any feedback is welcome!

Do I just build from this branch and run it with snowflake?

Yes, please.
Use make build; add the snowflake init hook in the volumes variable in config.toml; then start lstk via ./bin/lstk

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs: skip Pull request does not require documentation changes semver: patch

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants