simplecloud 0.0.1-beta.8 → 0.0.1-beta.81

package/README.md

@@ -67,6 +67,16 @@ node dist/cli.js --help
 node dist/cli.js start group test
 ```
 
+To test unpublished manifest changes from a local checkout:
+
+```bash
+SC_MANIFEST_DIR=../simplecloud-manifest \
+  bun dist/cli.js install service postgresql --yes
+```
+
+`SC_MANIFEST_DIR` makes both `components.yaml` and referenced service files load
+from that directory instead of the published GitHub manifest.
+
 ### Local Development
 
 **Option 1: Shell Alias (Recommended - No Conflicts)**
@@ -74,7 +84,7 @@ node dist/cli.js start group test
 Create a local `scl` alias that points to your development build:
 
 ```bash
-bun run local:setup  # Creates 'scl' alias in ~/.zshrc
+bun run local:setup  # Creates 'scl' and 'scld' aliases in ~/.zshrc
 source ~/.zshrc      # Reload shell config
 ```
 
@@ -87,6 +97,43 @@ scl start group mygroup
 
 **Pro Tip**: Run `bun run dev` in one terminal and use `scl` commands in another terminal for seamless development with auto-rebuilding!
 
+To test the current build in a fresh Linux environment without Java or Screen,
+use the disposable Docker runner:
+
+```bash
+scld setup
+scld server list
+scld network list
+scld --help
+```
+
+To reuse your current SimpleCloud login while keeping the rest of the sandbox
+clean, add `--host-session`:
+
+```bash
+scld --host-session network list
+scld --host-session setup
+scld --host-session shell
+```
+
+This copies only `~/.config/simplecloud/auth.json` into the disposable
+container. Host contexts and installation paths are intentionally not shared,
+and changes to the session inside the container do not modify the host file.
+
+The project is mounted read-only into an official Bun container. Credentials,
+Java, and installed SimpleCloud files are removed with the container when the
+command exits. A Linux Bun dependency volume is reused between runs and only
+refreshes when `package.json` or `bun.lock` changes. Every CLI command is
+supported. Use `scld shell` for a longer interactive session; the `scl` command
+is available inside it, so authentication and installation state remain
+available until you exit that shell.
+
+Without the local alias, run the same sandbox through Bun:
+
+```bash
+bun run scld -- setup
+```
+
 **Option 2: npm link (Development Symlink)**
 
 Creates symlinks to global npm location (uses same command names):
@@ -112,6 +159,55 @@ node dist/cli.js start group mygroup
 bunx swagger-typescript-api generate -p swagger.yaml -o src/lib/generated -n simplecloud-api.ts --sort-types --single-http-client --clean-output
 ```
 
+## Installing services during setup
+
+Manifest services are installed into the hidden `.services` directory inside
+the SimpleCloud installation:
+
+```bash
+simplecloud setup --yes --service postgresql
+```
+
+Repeat `--service` to create more instances. Instances receive stable,
+collision-free directory names and incremented default ports:
+
+```bash
+simplecloud setup --yes \
+  --service postgresql \
+  --service 'postgresql@players?database=players'
+```
+
+Service dependencies are resolved automatically. Selecting a database installs
+Docker when needed, verifies Docker Compose, renders all manifest files, and
+starts the service. Docker itself is a host installable and does not receive a
+service directory. Database storage is always backed by a named Docker volume.
+
+Services can also be added to an existing SimpleCloud installation through the
+existing `install` command:
+
+```bash
+simplecloud install service postgresql
+simplecloud install service postgresql \
+  --instance players \
+  --set database=players \
+  --set port=5433
+```
+
+The command uses the active SimpleCloud context, installs missing host
+dependencies such as Docker, writes the instance to `.services/<instance>`,
+and starts it. Use `--dry-run` to validate and inspect the plan without
+changing the installation.
+
+Installed service instances use the same lifecycle syntax as components:
+
+```bash
+simplecloud start postgresql
+simplecloud stop postgresql
+```
+
+Running `simplecloud start` or `simplecloud stop` without targets includes all
+installed components and services. Docker container names include the active
+network slug, for example `my-network-postgresql-database-1`.
 
 ## Publishing to npm