diff --git a/apps/docs/content/references/zsc.mdx b/apps/docs/content/references/zsc.mdx index 2c5c43d5..9e62f320 100644 --- a/apps/docs/content/references/zsc.mdx +++ b/apps/docs/content/references/zsc.mdx @@ -1,20 +1,11 @@ --- -title: Using Zerops Setup Control(Zsc) -description: Interacting with zerops containers by connecting to the project network via zcli vpn with wireguard. +title: Using Zerops Setup Control (zsc) +description: Command-line utility for managing Zerops containers, providing functionality for scaling, backups, environment management, and runtime operations --- -import Image from '/src/components/Image'; +# zsc (Zerops Setup Control) -Zerops Setup Control(Zsc) is a cli tool / helper installed to all containers, runtime and build, -which allows some direct modifications, like triggering scaling from inside the container, -adding new technologies, making sure that commands (like migration) run only once (even when -staring some high available setup with 3 containers) - -:::info -Zsc is automatically installed in all containers and is available both in runtime and build environments. -::: - -## Command Overview +Zsc is a management tool that comes pre-installed in all Zerops containers, providing functionality for container management, scaling and more. It's available in both runtime and build environments without any additional setup needed. ```sh zsc --help @@ -24,9 +15,7 @@ Usage: zsc [command] Available Commands: - action Perform specific predefined actions within the container backup-create creates a new backup of the specified stack - backup-current Create a new backup of the current stack completion Generate the autocompletion script for the specified shell connectSharedStorage Connect shared storage to the container crontab Perform crontab actions defined in zerops.yml @@ -42,78 +31,128 @@ Available Commands: Flags: -h, --help help for zsc - -Use "zsc [command] --help" for more information about a command. ``` -## Available Commands +## Command Overview -### backup-create and backup-current +### Backup Commands -The `backup-create` command lets you create a backup of any specified stack in your project, while `backup-current` command creates a backup of the stack you're currently working in. +#### backup-create +Create backup of a specified stack: -```sh -# Create backup of a specified stack +```bash zsc backup-create +``` + +Backup captures: +- Stack configuration +- Service data +- Environment settings +- Deployment state -# Create backup of the current stack you're working in -zsc backup-current + +### Core Management + +#### scale +Adjust container resources dynamically: + +```bash +# CPU Scaling +zsc scale cpu auto # Reset to automatic scaling +zsc scale cpu 5 1h # Set to 5 CPU cores for 1 hour +zsc scale cpu +2 30m # Add 2 CPU cores for 30 minutes + +# Memory Scaling +zsc scale memory auto # Reset to automatic scaling +zsc scale memory 5GB 1h # Set to 5GB RAM for 1 hour +zsc scale memory +2.5GB 600s # Add 2.5GB RAM for 600 seconds ``` -:::info -Backups include all the data and configurations of the stack at the time of backup creation. These can be used for recovery or creating duplicate environments. -::: +**Important Scaling Notes:** +- Changes take effect within ~10 seconds +- Minimum duration: 10 minutes +- Supported values: "auto", "min", "max", or numeric values +- RAM requires units (KiB, MiB, GiB) +- CPU values must be integers +- Use "+" prefix for relative scaling -### connectSharedStorage +#### execOnce +Ensure single execution across HA setups: -This command lets you connect a shared storage volume to your service for persistent data storage. +```bash +zsc execOnce "operation-key" "your-command" +``` -```sh +Common use cases: +- Database migrations +- One-time initialization tasks +- Configuration updates + +### Storage & Environment + +#### connectSharedStorage +Connect shared storage volumes: + +```bash zsc connectSharedStorage ``` -### crontab -This command lets you manage scheduled tasks that are defined in your zerops.yml configuration. +#### setSecretEnv +Manage environment variables: -```sh -zsc crontab +```bash +# Direct value assignment +zsc setSecretEnv SECRET_KEY "your-secret-value" + +# Input from stdin +echo "your-secret-value" | zsc setSecretEnv SECRET_KEY - ``` -### execOnce +### Testing & Debugging -:::info -This command is particularly useful in high-availability setups to ensure commands (like database migrations) run only once, even when starting multiple containers. -::: +#### test +Run various tests including network connectivity: -This command lets you execute a command exactly once across all containers in a service. Useful for database migrations in high-availability setups. +```bash +# TCP connectivity test +zsc test tcp : [options] -```sh -zsc execOnce "db-migration" "php artisan migrate" +# Options: +--timeout # Maximum test duration (default: 30s) +--dialTimeout # Single attempt timeout (default: 2s) +-4 # Force IPv4 +-6 # Force IPv6 ``` -### fail-me -This command lets you deliberately fail the current container for testing purposes. +#### fail-me +Deliberately fail the current container (useful for testing failover scenarios): -```sh +```bash zsc fail-me ``` -### install -You can install additional base technologies in your runtime container that weren't specified in the initial configuration. +#### noop +Keep container alive for debugging: + +```bash +zsc noop [--silent] +``` + +Features: +- Prevents container termination +- Enables investigation time +- Silent mode available +- Terminates on SIGTERM + +### Installation & Setup -:::info -The `install` command allows you to add technologies that weren't specified in the initial base configuration. -::: +#### install +Add technologies to your runtime container: -Example usage in `zerops.yml`: ```yaml +# Example in zerops.yml zerops: - setup: nodejsapp - build: - os: ubuntu - base: - - nodejs@22 - - python@3.7 run: os: ubuntu base: nodejs@22 @@ -121,86 +160,64 @@ zerops: - zsc install python@3.7 ``` -### noop -An infinitely blocking command that does nothing and keeps the container alive so that it doesn't end because of an error. The command runs indefinitely until it receives a SIGTERM signal. - -:::info -The `noop` command is particularly useful for debugging build failures by keeping the container alive for investigation. -::: +#### completion +Generate shell autocompletion scripts: -```sh -zsc noop [--silent] +```bash +zsc completion [bash|zsh|fish|powershell] ``` -The `--silent` flag suppresses any output from the command. +### Task Management -### scale -This command dynamically adjusts CPU or memory resources for the current container. +#### crontab +Manage scheduled tasks defined in zerops.yml: -:::caution -If there aren't enough resources available on the current node, using `scale` may trigger a container move to another node. This will reset the scale duration. -::: - -```sh -# Scale CPU -zsc scale cpu auto # Reset to automatic scaling -zsc scale cpu 5 1h # Scale to 5 CPU cores for 1 hour -zsc scale cpu +2 30m # Add 2 CPU cores for 30 minutes - -# Scale Memory -zsc scale memory auto # Reset to automatic scaling -zsc scale memory 5GB 1h # Scale to 5GB RAM for 1 hour -zsc scale memory +2.5GB 600s # Add 2.5GB RAM for 600 seconds +```bash +zsc crontab ``` -:::info -- Scaling takes effect within ~10 seconds -- Duration must be at least 10 minutes -- Supported values: "auto", "min", "max", or numeric values -- RAM values require units (KiB, MiB, GiB) -- CPU values must be integers without units -- Use "+" prefix for relative scaling -::: +## Best Practices -### test tcp -This command verifies TCP connectivity to a specified host and port. +1. **Resource Scaling** + - Use relative scaling for temporary adjustments + - Monitor resource usage after scaling + - Consider node capacity when scaling -```sh -zsc test tcp : [--timeout ] [--dialTimeout ] [-4] [-6] -``` - -- **``**: Server address to connect to -- **``**: Port number to connect to -- **`--timeout `**: Maximum test duration (default: 30s) -- **`--dialTimeout `**: Single attempt timeout (default: 2s) -- **`-4`**: Force IPv4 -- **`-6`**: Force IPv6 +2. **High Availability** + - Use `execOnce` for migrations + - Test failover with `fail-me` + - Implement proper timeout handling -Example: -```sh -zsc test tcp database:5432 --timeout 1m -``` +3. **Debugging** + - Use `noop` for investigation + - Implement proper logging + - Monitor container states -### setSecretEnv -This command sets a secret environment variable in the current stack context. +## Common Use Cases -```sh -zsc setSecretEnv [key] [content] [flags] +### Database Migration in HA Setup +```bash +zsc execOnce "migrate-v2" "php artisan migrate" ``` -Examples: -```sh -# Direct value -zsc setSecretEnv SECRET_KEY "new_value" - -# From stdin -echo "new_value" | zsc setSecretEnv SECRET_KEY - +### Temporary Resource Boost +```bash +zsc scale cpu +2 1h +zsc scale memory +1GB 1h ``` -### version -This command displays the current version of Zsc CLI. +### Testing HA Failover +```bash +zsc fail-me # On one container +zsc test tcp other-service:80 # Verify connectivity after failover +``` -```sh -zsc version +### Secret Management +```bash +zsc setSecretEnv API_KEY "$(generate_api_key)" ``` +## Additional Information + +- View all commands and options with `zsc --help` +- Check version information with `zsc version`