Add support for time shifting inside the container

[leighmcculloch]

What

Install faketime in the container image and configure libfaketime via ld.so.preload so all processes see the modified time. Expose time control through /etc/faketimerc, defaulting to +0 (no modification). Pass FAKETIME_NO_CACHE through to supervisord so changes take effect immediately. Document time manipulation via volume-mounted config, offset syntax, progressive jumps, and speed multipliers.

Why

Testing time-sensitive Stellar network behavior (e.g. ledger close times, expiry) requires advancing the clock without affecting the host or restarting the container. libfaketime intercepts time calls at the libc level, making it transparent to all services.

This probably doesn't allow for testing all time movement situations, but it's a simple way to provide some ability to do that with quickstart. Generally the soroban-sdk test framework is still the best place to codify tests that involve time changing.

Close stellar/stellar-protocol#1897

[Copilot]

Pull request overview

Adds container-wide time shifting support for Stellar Quickstart by integrating libfaketime and documenting how to control the fake time via /etc/faketimerc.

Changes:

• Install faketime-related packages in the image and preload libfaketime for all processes.
• Add a default /etc/faketimerc and pass FAKETIME_NO_CACHE through to supervisord-launched services.
• Document how to modify time in a running container via a bind-mounted faketimerc file.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
start	Passes FAKETIME_NO_CACHE into the clean supervisord environment.
dependencies	Adds a faketime package to the apt install list.
Dockerfile	Attempts to symlink and preload libfaketime.so.1, sets FAKETIME_NO_CACHE=1, and copies /etc/faketimerc.
faketimerc	Introduces the default faketime configuration file content.
README.md	Documents time modification usage and examples.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

FAKETIME_NO_CACHE only enables libfaketime’s no-cache mode when set to 1; if it’s unset (or set to an empty string), config changes may not take effect immediately. Since env -i rebuilds the environment, consider defaulting it here (e.g., use a ${FAKETIME_NO_CACHE:-1}-style default) so the documented “take effect immediately” behavior holds even if the variable wasn’t set upstream.

Suggested change

	FAKETIME_NO_CACHE="$FAKETIME_NO_CACHE" \
	FAKETIME_NO_CACHE="${FAKETIME_NO_CACHE:-1}" \

[Copilot]

apt-get install adds faketime, but on Ubuntu 24.04 the faketime package only provides the /usr/bin/faketime wrapper; the preload library (libfaketime.so.1) comes from the libfaketime package. As written, the later Dockerfile steps that reference /usr/lib/*/faketime/libfaketime.so.1 will fail or produce a broken /etc/ld.so.preload entry. Install libfaketime (and only keep faketime if you also need the wrapper).

Suggested change

	libunwind8 sqlite3 libc++abi1-20 libc++1-20 faketime'
	libunwind8 sqlite3 libc++abi1-20 libc++1-20 faketime libfaketime'

[leighmcculloch]

Todo:

• Wait on feedback before iterating on this further: Local Single-Node Time Control for Quickstart stellar-protocol#1897 (comment)
• Check if this adversely affects performance of the image.
• Add a test that uses it.