diff --git a/apps/docs/content/features/pipeline.mdx b/apps/docs/content/features/pipeline.mdx index bf8c9110..9eda0200 100644 --- a/apps/docs/content/features/pipeline.mdx +++ b/apps/docs/content/features/pipeline.mdx @@ -111,7 +111,7 @@ Trigger the build & deploy pipeline automatically with each push to the selected To start a new build & deploy pipeline manually, use the [Zerops CLI](/references/cli). zCLI is the Zerops command-line tool. -The [zcli push](/references/cli/commands#push) command uploads your application code, builds and deploys your application in Zerops. +The [zcli service push](/references/cli/commands#service-push) command uploads your application code, builds and deploys your application in Zerops. The command triggers the build pipeline defined in `zerops.yaml`. `zerops.yaml` must be in the working directory. The working directory is by default the current directory and can be changed using the `--workingDir` flag. diff --git a/apps/docs/content/references/cli.mdx b/apps/docs/content/references/cli.mdx index fa01d473..65afba04 100644 --- a/apps/docs/content/references/cli.mdx +++ b/apps/docs/content/references/cli.mdx @@ -6,7 +6,9 @@ description: Learn how to install and use zCLI, the powerful command-line tool f import CustomCard from '/src/components/CustomCard'; import Image from '/src/components/Image'; -zCLI is the command-line tool for Zerops that allows users to manage services, simplify interactions, configure infrastructure directly from the terminal. +zCLI is the command-line tool for Zerops that allows users to manage services, simplify interactions, and configure infrastructure directly from the terminal. + +For detailed information, see the [Configuration](/references/cli/configuration) and [Commands Reference](/references/cli/commands) pages. ## Platforms @@ -101,8 +103,4 @@ You may use an access token to access Zerops using this command: ```sh zcli login -``` - -## References - -[zCLI Commands and Usage](/references/cli/commands) \ No newline at end of file +``` \ No newline at end of file diff --git a/apps/docs/content/references/cli/access-logs.mdx b/apps/docs/content/references/cli/access-logs.mdx deleted file mode 100644 index dca65bab..00000000 --- a/apps/docs/content/references/cli/access-logs.mdx +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: How to access logs via zCLI -description: Learn more about how you can access your logs via zCLI. ---- - -To start the VPN you need first [install & setup zCLI](/references/cli), the Zerops command-line tool. - -## Build log - -To access a build log in Zerops CLI use - -```sh -zcli service log --showBuildLogs -``` - -The command returns the build log to `stdout` with a streaming option. By default the command returns the last 100 log messages and exits. Use the `--follow` flag to continuously pool for new log messages. - -#### Command annotation - -```sh -Usage: - zcli service log [flags] - -Flags: - --follow If set, zCLI will continuously poll for new log messages. By default, the command will exit - once there are no more logs to display. To exit from this mode, use Control-C. - --format string The format of returned log messages. Following formats are supported: - FULL: This is the default format. Messages will be returned in the complete Syslog format. - SHORT: Returns only timestamp and log message. - JSON: Messages will be returned as one JSON object. - JSONSTREAM: Messages will be returned as stream of JSON objects. (default "FULL") - --formatTemplate string Set a custom log format. Can be used only with --format=FULL. - Example: --formatTemplate="{{.timestamp}} {{.severity}} {{.facility}} {{.message}}". - Supports standard GoLang template format and functions. - -h, --help the service log command. - --limit int How many of the most recent log messages will be returned. Allowed interval is <1;1000>. - Default value = 100. (default 100) - --messageType string Select either APPLICATION or WEBSERVER log messages to be returned. Default value = APPLICATION. (default "APPLICATION") - --minimumSeverity string Returns log messages with requested or higher severity. Set either severity number in the interval - <0;7> or one of following severity codes: - EMERGENCY, ALERT, CRITICAL, ERROR, WARNING, NOTICE, INFORMATIONAL, DEBUG. - --projectId string If you have access to more than one project, you must specify the project ID for which the - command is to be executed. - --serviceId string If you have access to more than one service, you must specify the service ID for which the - command is to be executed. - --showBuildLogs If set, zCLI will return build log messages instead of runtime log messages. -``` - -zCLI commands are interactive, when you press enter after `zcli service log`, you will be given a list of your projects to choose from. - -## Runtime log - -To access the log of the first runtime container in Zerops CLI use - -```sh -zcli service log -``` - -The command returns the runtime log of the first container to `stdout` with a streaming option. By default the command returns the last 100 log messages and exits. Use the `--follow` flag to continuously pool for new log messages. diff --git a/apps/docs/content/references/cli/commands.mdx b/apps/docs/content/references/cli/commands.mdx index 28209337..24c9d4a0 100644 --- a/apps/docs/content/references/cli/commands.mdx +++ b/apps/docs/content/references/cli/commands.mdx @@ -1,18 +1,22 @@ --- -title: Available Commands -description: Available commands in the Zerops command line tool (zcli) +title: Zerops CLI Commands Reference +description: A comprehensive reference for all available commands in the Zerops command line tool (zcli) --- ## Basic Usage ```sh -zcli [command] [flags] +zcli [flags] ``` :::note Tip All commands support the `-h, --help` flag which displays help information about the command. ::: +:::tip Configuration +For detailed information about configuration options, environment variables, and logging, see the [Zerops CLI Configuration](/references/cli/configuration) page. +::: + ## Command Groups - [Account & VPN](#account--vpn) - [Project Management](#project-management) @@ -50,6 +54,10 @@ zcli vpn up [projectId] [flags] - `--mtu int` - Set custom MTU value for Wireguard interface (default: 1420) - `--projectId string` - Required when you have access to multiple projects +:::note +You can set a default project ID for VPN connections in a `.zcli.yml` file or via the `ZEROPS_PROJECTID` environment variable. See the [Configuration](/references/cli/configuration) page for details. +::: + ### vpn down Disconnects from the Zerops VPN. @@ -115,6 +123,10 @@ Sets the default project for commands that require a project ID. zcli scope project [projectId] ``` +:::tip +Instead of using the `scope project` command, you can also set a default project ID in a `.zcli.yml` file or via the `ZEROPS_PROJECTID` environment variable. See the [Configuration](/references/cli/configuration) page for details. +::: + ### scope reset Resets the default project and service scope. @@ -148,6 +160,7 @@ zcli service push [serviceIdOrName] [flags] - `--archiveFilePath string` - Creates a tar.gz archive with application code - `-g, --deployGitFolder` - Include the .git folder in the upload - `--disableLogs` - Disable logs during push +- `-v, --verbose` - Log additional debug data to the zCLI [debug log file](/references/cli/configuration#logging-configuration) - `--projectId string` - Required when you have access to multiple projects - `--serviceId string` - Required when you have access to multiple services - `--setup string` - Choose setup to use from zerops.yml @@ -161,6 +174,8 @@ zcli service push [serviceIdOrName] [flags] :::tip You can also use `zcli push` as a shorthand for `zcli service push`. + +To avoid specifying `--projectId` and `--serviceId` flags repeatedly, you can set default values in a `.zcli.yml` file or via environment variables. See the [Configuration](/references/cli/configuration) page for details. ::: ### service deploy diff --git a/apps/docs/content/references/cli/configuration.mdx b/apps/docs/content/references/cli/configuration.mdx new file mode 100644 index 00000000..caba667c --- /dev/null +++ b/apps/docs/content/references/cli/configuration.mdx @@ -0,0 +1,113 @@ +--- +title: Zerops CLI Configuration +description: Configuration options, environment variables, and logging capabilities for the Zerops command line tool (zcli) +--- + +:::tip Commands Reference +For a comprehensive reference of all available commands, see the [Commands Reference](/references/cli/commands) page. +::: + +## Configuration Overview + +You can configure default values for zCLI commands using the following methods (in order of increasing precedence): + +1. [Configuration files](#configuration-files) +2. [Environment variables](#environment-variables) +3. [Command-line flags](/references/cli/commands) + +:::note Precedence +This precedence order means that command-line flags will override environment variables, which will override settings in configuration files. +::: + +## Configuration Files + +zCLI supports configuration via YAML files in the following locations: + +1. Global config (user home): `~/.config/zerops/zcli.yaml` or `~/zerops/zcli.yaml` +2. Project-specific config: `./.zcli.yaml` in the root of your application repository + +The system first loads the global config file, then merges in the project-specific config if it exists: +- Settings unique to the global config are preserved +- Settings in the project-specific config will override any duplicate keys from the global config + +### Configuration File Examples + +**Global config file (placed in user home directory):** +```yaml +# Set organization-wide defaults +workspaceState: "all" +``` + +**Project-specific `.zcli.yml` file (placed in the root of your application repository):** +```yaml +# Set project-specific settings +projectId: "your-project-id" +serviceId: "your-service-id" + +# Override global workspace state for this project +workspaceState: "clean" +``` + +## Environment Variables + +### Standard Environment Variables + +Any flag can be set via environment variables by: +- Using the `ZEROPS_` prefix +- Converting the flag name to uppercase +- Using the full flag name (not shorthand) + +**Example:** +```sh +export ZEROPS_WORKSPACESTATE=clean +export ZEROPS_PROJECTID=your-project-id +``` + +### Special Environment Variables + +zCLI also recognizes special environment variables that control its behavior: + +#### Terminal Mode Configuration + +The `ZEROPS_CLI_TERMINAL_MODE` environment variable controls the interactive mode of zCLI: + +```sh +export ZEROPS_CLI_TERMINAL_MODE= +``` + +Available modes: +- `auto` (default): Automatically detects if interactive mode can be used and enables it when possible +- `enabled`: Forces interactive mode to be enabled +- `disabled`: Forces interactive mode to be disabled + +This setting affects interactive prompts, progress indicators, and other terminal-based user interface elements. + +#### Logging Configuration + +zCLI maintains a debug log file for the `service push` and `service deploy` commands. This logging feature is designed specifically for debugging purposes. The log file can be found in one of these locations: + +**1. Default locations** (checked in this order): + - `/var/log/zcli.log` (if zCLI has write permissions) + - `~/.config/zerops/zerops.log` (as fallback) + +**2. Custom location** (if specified): + - Set with `ZEROPS_CLI_LOG_FILE_PATH` environment variable + +:::note +zCLI must have write permissions for the specified log file locations. +::: + +To enable verbose logging with additional debug information, use the `--verbose` flag (or its shorthand `-v`): +```sh +zcli service push --verbose +zcli service push -v +``` + +To troubleshoot deployment issues, you can check these log files using commands like `cat` or `tail`: +```sh +# View the entire log file +cat ~/.config/zerops/zerops.log + +# Stream new log entries +tail -f ~/.config/zerops/zerops.log +``` \ No newline at end of file diff --git a/apps/docs/sidebars.js b/apps/docs/sidebars.js index 4e6a7889..2099681f 100644 --- a/apps/docs/sidebars.js +++ b/apps/docs/sidebars.js @@ -521,16 +521,16 @@ module.exports = { items: [ { type: 'doc', - id: 'references/cli/commands', - label: 'Available Commands', + id: 'references/cli/configuration', + label: 'Configuration', customProps: { exclude_from_doc_list: false, }, }, { type: 'doc', - id: 'references/cli/access-logs', - label: 'Access Logs', + id: 'references/cli/commands', + label: 'Commands', customProps: { exclude_from_doc_list: false, }, diff --git a/apps/docs/static/llms-full.txt b/apps/docs/static/llms-full.txt new file mode 100644 index 00000000..c56ac20b --- /dev/null +++ b/apps/docs/static/llms-full.txt @@ -0,0 +1,50422 @@ +This is the full developer documentation for Zerops. + +# Start of Zerops documentation + + + + sample answer + + + + + +This quick start allows you to get hands-on experience of Zerops, whether you only want to see it in action or want to start small and scale up the project size later. The purpose of this guide is to get an existing Bun application up and running easily. + +If you are already familiar with Zerops and you are interested in more detailed guides for your own application, feel free to head straight to the [How to](bun/how-to/create) section. + +## Guides + +We have created a repository, a _recipe_, containing the most simple Bun web application, so you don't need to write any code yet. Choose from the options below which suits you best: + + + +### Other recipes + + + +:::tip +Did none of these Guides fit your needs? Join our **[Discord](https://discord.com/invite/WDvCZ54)** community to get help from our team and other members. +::: + + + +## Private internal access + +Projects in Zerops represent a group of one or more services. +Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its [internal port](bun/how-to/build-pipeline#ports). + +To connect to your application with `app` hostname running on [internal port](bun/how-to/build-pipeline#ports) `3000`, simply use `http://app:3000` + +:::info +Do not use `https://` when communicating with Bun from other runtime services in the same project. The internal communication is done over a private network and is isolated from other projects. +::: + +### Use Bun environment variables + +Zerops creates default environment variables for each Bun service to help you with connection within the same project. To avoid the need to copy the access parameters manually, use [generated environment variables](bun/how-to/env-variables#generated-env-variables) of the Bun service. + +#### Prefix the environment variable key + +All services of the same project can reference environment variables from other services. To use an environment variable from one service in another service in the same project, you must prefix the environment variable key with the service hostname and underscore. + +#### Example: + +To access the `API_TOKEN` env variable of the `app` service, use `app_API_TOKEN` as the env variable key. + +Read more about [env variables](bun/how-to/env-variables). + +## Private access via VPN + +### Start VPN connection + +You can securely connect to your Bun application from your local workspace via Zerops VPN. Zerops VPN client is included into zCLI, the Zerops command-line tool. To start a VPN connection to the selected Zerops project, follow these steps: + +1. [Install & setup zCLI](/references/cli) +2. [Start the Zerops VPN](/references/vpn#start-vpn) + +### Access Bun application through VPN + +Once the VPN session is established, you have the secured connection to the project's private network in Zerops. You can access all project services locally by using their hostname. The only difference is that no [environment variables](bun/how-to/env-variables) are available when connected through VPN. To connect to your Bun application in Zerops set the hostname and [internal port](bun/how-to/build-pipeline#ports) e.g. http://app:3000 + +:::info +Do not use `https://` when communicating with Bun over the VPN. The security is assured by the VPN. The internal communication is done over a private network and is isolated from other projects. +::: + +### Connect via SSH + +Use the `ssh` command to connect to your service via SSH. + +### Stop VPN connection + +[Stop the Zerops VPN](/references/vpn#stop-vpn) in zCLI. + +## Public access through zerops.io subdomain + +By default, your Bun service is not publicly accessible. To test your application, enable the [public access through zerops.io subdomain](/features/access#public-access-through-zerops-subdomain). + +## Public access through your domain + +By default, your Bun service is not publicly accessible. When your application is ready for production or if you want to test it on the production domain, [configure the public access through your domain](/features/access#public-access-through-your-domain). + +## Public access from another Zerops project + +All services of the same project share a dedicated private network. To connect to a service within the same project, just use the service hostname and its [internal port](bun/how-to/build-pipeline#ports). Different projects are not connected inside Zerops. To connect to a runtime service from another Zerops project, you need to use public access either [through zerops.io subdomain](/features/access#public-access-through-zerops-subdomain) or [through your domain](/features/access#public-access-through-your-domain). + + + + + +Zerops provides a customizable build and runtime environment for your Bun application. + +## Add zerops.yaml to your repository + +Start by adding `zerops.yaml` file to the **root of your repository** and modify it to fit your application: + +```yaml +zerops: + # define hostname of your service + - setup: app + # ==== how to build your application ==== + build: + # REQUIRED. Set the base technology for the build environment: + base: bun@latest + + # OPTIONAL. Set the operating system for the build environment. + # os: ubuntu + + # OPTIONAL. Customise the build environment by installing additional packages + # or tools to the base build environment. + # prepareCommands: + # - apt-get something + # - curl something else + + # REQUIRED. Build your application + buildCommands: + - bun i + - bun run build + + # REQUIRED. Select which files / folders to deploy after + # the build has successfully finished + deployFiles: + - dist + - package.json + - node_modules + + # OPTIONAL. Which files / folders you want to cache for the next build. + # Next builds will be faster when the cache is used. + cache: node_modules + + # ==== how to run your application ==== + run: + # OPTIONAL. Sets the base technology for the runtime environment: + base: bun@latest + + # OPTIONAL. Sets the internal port(s) your app listens on: + ports: + # port number + - port: 3000 + + # OPTIONAL. Customise the runtime Bun environment by installing additional + # dependencies to the base Bun runtime environment. + # prepareCommands: + # - apt-get something + # - curl something else + + # OPTIONAL. Run one or more commands each time a new runtime container + # is started or restarted. These commands are triggered before + # your Bun application is started. + # initCommands: + # - rm -rf ./cache + + # REQUIRED. Your Bun application start command + start: bun start +``` + +The top-level element is always `zerops`. + +### Setup + +The first element `setup` contains the **hostname** of your service. A runtime service with the same hostname must exist in Zerops. +Zerops supports the definition of multiple runtime services in a single `zerops.yaml`. This is useful when you use a monorepo. Just add multiple setup elements in your `zerops.yaml`: + +```yaml +zerops: + # definition for app service + - setup: app + build: ... + run: ... + + # definition for api service + - setup: api + build: ... + run: ... +``` + +Each service configuration contains at least two sections: **build** and **run**. Both sections are required to build and deploy your Bun application in Zerops. If you'd like to use a readiness check, add an optional **deploy** section. + +## Build pipeline configuration + +### base + +_REQUIRED._ Sets the base technology for the build environment. + +Following options are available for Bun builds: + + + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + # REQUIRED. Sets the base technology for the build environment: + base: bun@latest + ... +``` + +

+ The base build environment contains {data.alpine.default}, the selected + major version of Bun, + Zerops command line tool, `npm`, + `yarn`, `git` and `npx` tools. +

+ +:::info +You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository. +::: + +If you need to install more technologies to the build environment, set multiple values as a yaml array. For example: + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + # REQUIRED. Sets the base technology for the build environment: + base: + - bun@latest + prepareCommands: + - zsc add go@latest + ... +``` + +See the full list of supported [build base environments](/zerops-yaml/base-list#runtime-services). + +To customise your build environment use the [prepareCommands](bun/how-to/build-pipeline#preparecommands) attribute. + +:::note +Modifying the base technology will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for more details about cache invalidation. +::: + +### os + +_OPTIONAL._ Sets the operating system for the build environment. + +Following options are available: + +- `alpine` +- `ubuntu` + +Default value is `alpine`. + +We are currently using following os version: + +- {data.alpine.default} +- {data.ubuntu.default} + +:::caution +The os version is fixed and cannot be customised. +::: + +:::note +Changing the OS setting will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache behavior. +::: + +### prepareCommands + +_OPTIONAL._ Customises the build environment by installing additional dependencies or tools to the base build environment. + +The base build environment contains: + +- {data.alpine.default} +- selected version of Bun defined in the [base](bun/how-to/build-pipeline#base) attribute +- [Zerops command line tool](/references/cli) +- `npm`, `yarn`, `git` and `npx` tools + +To install additional packages or tools add one or more prepare commands: + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + # REQUIRED. Set the base technology for the build environment: + base: bun@latest + + # OPTIONAL. Customise the build environment by installing additional packages + # or tools to the base build environment. + prepareCommands: + - apt-get something + - curl something else + ... +``` + +When the first build is triggered, Zerops will + +1. create a build container +2. download your application code from your repository +3. run the prepare commands in the defined order + +The application code is available in the `/var/www` folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file). + +:::note +These commands are skipped when using cached environment. Modifying `prepareCommands` will invalidate your build cache. See our [Build Cache Documentation](/features/build-cache) for details about cache invalidation. +::: + +#### Command exit code + +If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](bun/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all prepare commands are finished, your custom build environment is ready for the build phase. + +#### Single or separated shell instances + +You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands). + +### buildCommands + +_REQUIRED._ Defines build commands. + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + # REQUIRED. Set the base technology for the build environment: + base: bun@latest + + # REQUIRED. Build your application + buildCommands: + - bun i + - bun run build + ... +``` + +At least one command is required. Zerops triggers each command in the defined order in a dedicated build container. + +Before the build commands are triggered the build container contains: + +1. base environment defined by the [base](bun/how-to/build-pipeline#base) attribute +2. optional customisation of the base environment defined in the [prepareCommands](bun/how-to/build-pipeline#preparecommands) attribute +3. your application code + +#### Run build commands as a single shell instance + +Use following syntax to run all commands in the same environment context. For example, if one command changes the current directory, the next command continues in that directory. When one command creates an environment variable, the next command can access it. + +```yaml +buildCommands: + - | + bun i + bun run build +``` + +#### Run build commands as a separate shell instances + +When the following syntax is used, each command is triggered in a separate environment context. For example, each shell instance starts in the home directory again. When one command creates an environment variable, it won't be available for the next command. + +```yaml +buildCommands: + - bun i + - bun run build +``` + +#### Command exit code + +If any command fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](bun/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the --verbose option. + +```yaml +buildCommands: + - bun i --verbose + - bun run build +``` + +If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the deploy phase. + +### deployFiles + +_REQUIRED._ Selects which files or folders will be deployed after the build has successfully finished. To filter out specific files or folders, use `.deployignore` file. + +```yaml +# REQUIRED. Select which files / folders to deploy after +# the build has successfully finished +deployFiles: + - dist + - package.json + - node_modules +``` + +Determines files or folders produced by your build, which should be deployed to your runtime service containers. + +The path starts from the **root directory** of your project (the location of `zerops.yaml`). You must enclose the name in quotes if the folder or the file name contains a space. + +The files/folders will be placed into `/var/www` folder in runtime, e.g. `./src/assets/fonts` would result in `/var/www/src/assets/fonts`. + +#### Examples + +Deploys a folder, and a file from the project root directory: + +```yaml +deployFiles: + - dist + - package.json +``` + +Deploys the whole content of the build container: + +```yaml +deployFiles: . +``` + +Deploys a folder, and a file in a defined path: + +```yaml +deployFiles: + - ./path/to/file.txt + - ./path/to/dir/ +``` + +#### How to use a wildcard in the path + +Zerops supports the `~` character as a wildcard for one or more folders in the path. + +Deploys all `file.txt` files that are located in any path that begins with `/path/` and ends with `/to/` + +```yaml +deployFiles: ./path/~/to/file.txt +``` + +Deploys all folders that are located in any path that begins with `/path/to/` + +```yaml +deployFiles: ./path/to/~/ +``` + +Deploys all folders that are located in any path that begins with `/path/` and ends with `/to/` + +```yaml +deployFiles: ./path/~/to/ +``` + +:::note Example +By default, `./src/assets/fonts` deploys to `/var/www/src/assets/fonts`, keeping the full path. Adding `~`, like `./src/assets/~fonts`, shortens it to `/var/www/fonts` +::: +#### .deployignore + +Add a `.deployignore` file to the root of your project to specify which files and folders Zerops should ignore during deploy. The syntax follows the same pattern format as `.gitignore`. + +To ignore a specific file or directory path, start the pattern with a forward slash (`/`). Without the leading slash, the pattern will match files with that name in any directory. + +:::tip +For consistency, it's recommended to configure both your `.gitignore` and `.deployignore` files with the same patterns. +::: + +Examples: + +```yaml title="zerops.yaml" +zerops: + - setup: app + build: + deployFiles: ./ +``` + +```text title=".deployignore" +/src/file.txt +``` +The example above ignores `file.txt` only in the root src directory. +```text title=".deployignore" +src/file.txt +``` +This example above ignores `file.txt` in ANY directory named `src`, such as: +- `/src/file.txt` +- `/folder2/folder3/src/file.txt` +- `/src/src/file.txt` + +:::note +`.deployignore` file also works with `zcli service deploy` command. +::: + +### cache + +_OPTIONAL._ Defines which files or folders will be cached for the next build. + +```yaml +# OPTIONAL. Which files / folders you want to cache for the next build. +# Next builds will be faster when the cache is used. +cache: file.txt +``` + +The cache attribute helps optimize build times by preserving specified files between builds. + +The cache attribute supports the [~ wildcard character](#how-to-use-a-wildcard-in-the-path). + +Learn more about the [build cache system](/features/build-cache) in Zerops. + +### envVariables + +_OPTIONAL._ Defines the environment variables for the build environment. + +Enter one or more env variables in following format: + +```yaml +zerops: + # define hostname of your service + - setup: app + # ==== how to build your application ==== + build: + base: bun@latest + … + + # OPTIONAL. Defines the env variables for the build environment: + envVariables: + NODE_ENV: production + DB_NAME: db + DB_HOST: db + DB_USER: db + DB_PASS: ${db_password} +``` + +Read more about [environment variables](bun/how-to/env-variables) in Zerops. + +## Runtime configuration + +### base + +_OPTIONAL._ Sets the base technology for the runtime environment. +If you don't specify the `run.base` attribute, Zerops keeps the current Bun version for your runtime. + +Following options are available for Bun runtimes: + + + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + # REQUIRED. Sets the base technology for the build environment: + base: bun@latest + ... + + # ==== how to run your application ==== + run: + # OPTIONAL. Sets the base technology for the runtime environment: + base: bun@latest + ... +``` + +

+ The base runtime environment contains {data.alpine.default}, the + selected major version of Bun, Zerops command line tool, `npm`, `yarn`, `git` and `npx` tools. +

+ +:::info +You can change the base environment when you need to. Just simply modify the `zerops.yaml` in your repository. +::: + +If you need to install more technologies to the runtime environment, set multiple values as a yaml array. For example: + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + # REQUIRED. Sets the base technology for the build environment: + base: bun@latest + ... + + # ==== how to run your application ==== + run: + # OPTIONAL. Sets the base technology for the runtime environment: + base: + - bun@latest + prepareCommands: + - zsc add go@latest + ... +``` + +See the full list of supported [run base environments](/zerops-yaml/base-list). + +To customise your build environment use the `prepareCommands` attribute. + +### os + +_OPTIONAL._ Sets the operating system for the runtime environment. + +Following options are available: + +- `alpine` +- `ubuntu` + +Default value is `alpine`. + +We are currently using following os version: + +- {data.alpine.default} +- {data.ubuntu.default} + +:::caution +The os version is fixed and cannot be customised. +::: + +### ports + +_OPTIONAL._ Specifies one or more internal ports on which your application will listen. + +Projects in Zerops represent a group of one or more services. Services can be of different types (runtime services, databases, message brokers, object storage, etc.). All services of the same project share a **dedicated private network**. To connect to a service within the same project, just use the service hostname and its internal port. + +For example, to connect to a Bun service with hostname = "app" and port = 3000 from another service of the same project, simply use `app:3000`. Read more about [how to access a Bun service](bun/how-to/access). + +Each port has following attributes: + +| parameter | description | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| port | Defines the port number. You can set any port number between _10_ and _65435_. Ports outside this interval are reserved for internal Zerops systems. | +| protocol | **Optional.** Defines the protocol. Allowed values are `TCP` or `UDP`. Default value is `TCP`. | +| httpSupport | **Optional.** `httpSupport = true` is the default setting for TCP protocol. Set `httpSupport = false` if a web server isn't running on the port. Zerops uses this information for the configuration of [public access](/features/access). `httpSupport = true` is available only in combination with the TCP protocol. | + +### prepareCommands + +_OPTIONAL._ Customises the Bun runtime environment by installing additional dependencies or tools to the runtime base environment. + +

+ The base Bun environment contains {data.alpine.default} the selected + major version of Bun, Zerops command line tool and `npm`, `yarn`, `git` and `npx` tools. To install + additional packages or tools add one or more prepare commands: +

+ +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + ... + + # ==== how to run your application ==== + run: + # OPTIONAL. Customise the runtime environment by installing additional packages + # or tools to the base Bun runtime environment. + prepareCommands: + - apt-get something + - curl something else + ... +``` + +When the first deploy with a defined prepare attribute is triggered, Zerops will + +1. create a prepare runtime container +2. optionally: [copy selected folders or files from your build container](bun/how-to/build-pipeline#copy-folders-or-files-from-your-build-container) +3. run the `prepareCommands` commands in the defined order + +#### Command exit code + +If any command fails, it returns an exit code other than 0 and the deploy is canceled. Read the [prepare runtime log](bun/how-to/logs#prepare-runtime-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom runtime environment is ready for the deploy phase. + +#### Cache of your custom runtime environment + +Some packages or tools can take a long time to install. Therefore, Zerops caches your custom runtime environment after the installation of your custom packages or tools is completed. When the second or following deploy is triggered, Zerops will use the custom runtime cache from the previous deploy if following conditions are met: + +1. Content of the [build.addToRunPrepare](#copy-folders-or-files-from-your-build-container) and `run.prepareCommands` attributes didn't change from the previous deploy +2. The custom runtime cache wasn't invalidated in the Zerops GUI. + +To invalidate the custom runtime cache go to `yyy` + +{/*TODO screenshot*/} + +When the custom runtime cache is used, Zerops doesn't create a prepare runtime container and executes the deployment of your application directly. + +#### Single or separated shell instances + +You can configure your prepare commands to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands). + +### Copy folders or files from your build container + +

+ The prepare runtime container contains {data.alpine.default}, the selected major version of Bun, Zerops command line tool and `npm`, + `yarn`, `git` and `npx` tools. +

+ +The prepare runtime container does not contain your application code nor the built application. If you need to copy some folders or files from the build container to the runtime container (e.g. a configuration file) use the `addToRunPrepare` attribute in the [build section](#build-pipeline-configuration). + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: + ... + addToRunPrepare: ./runtime-config.yaml + + # ==== how to run your application ==== + run: + # OPTIONAL. Customise the runtime environment by installing additional packages + # or tools to the base Bun runtime environment. + prepareCommands: + - apt-get something + - curl something else + ... +``` + +In the example above Zerops will copy the `runtime-config.yaml` file from your build container **after the build has finished** into the new **prepare runtime** container. The copied files and folders will be available in the `xxx` folder in the new prepare runtime container before the prepare commands are triggered. + +### initCommands + +_OPTIONAL._ Defines one or more commands to be run each time a new runtime container is started or a container is restarted. + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: ... + + # ==== how to run your application ==== + run: + # OPTIONAL. Run one or more commands each time a new runtime container + # is started or restarted. These commands are triggered before + # your Bun application is started. + initCommands: + - rm -rf ./cache +``` + +These commands are triggered in the runtime container before your Bun application is started via the [start command](bun/how-to/build-pipeline#start). + +Use init commands to clean or initialise your application cache or similar operations. + +:::caution +The init commands will delay the start of your application each time a new runtime container is started (including the [horizontal scaling](bun/how-to/scaling#horizontal-auto-scaling) or when a runtime container is restarted). + +Do not use the init commands for customising your runtime environment. Use the [run:prepareCommands](bun/how-to/build-pipeline#preparecommands1) attribute instead. +::: + +#### Command exit code + +If any of the `initCommands` fails, it returns an exit code other than 0, but deploy is **not** canceled. After all init commands are finished, regardless of the status code, the application is started. Read the [runtime log](bun/how-to/logs#runtime-log) to troubleshoot the error. + +#### Single or separated shell instances + +You can configure your `initCommands` to be run in a single shell instance or multiple shell instances. The format is identical to [build commands](#buildcommands). + +### envVariables + +_OPTIONAL._ Defines the environment variables for the runtime environment. + +Enter one or more env variables in following format: + +```yaml +zerops: + # define hostname of your service + - setup: app + # ==== how to run your application ==== + run: + # OPTIONAL. Defines the env variables for the runtime environment: + envVariables: + NODE_ENV: production + DB_NAME: db + DB_HOST: db + DB_USER: db + DB_PASS: ${db_password} +``` + +Read more about [environment variables](bun/how-to/env-variables) in Zerops. + +### start + +_REQUIRED._ Defines the start command for your Bun application. + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: ... + + # ==== how to run your application ==== + run: + # REQUIRED. Your Bun application start command + start: bun start +``` + +We recommend starting your Bun application using `bun start`. + +### health check + +_OPTIONAL._ Defines a health check. + +`healthCheck` requires either one `httpGet` object or one `exec` object. + +#### httpGet + +Configures the health check to request a local URL using a HTTP GET method. + +Following attributes are available: + +| Parameter | Description | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **port** | Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on `http://127.0.0.1:{port}/{path}` | +| **path** | Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on `http://127.0.0.1:{port}/{path}` | +| **host** | **Optional.** The readiness check is triggered from inside of your runtime container so it always uses the localhost (`127.0.0.1`). If you need to add a `host` to the request header, specify it in the `host` attribute. | +| **scheme** | **Optional.** The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set `scheme: https` | + +**Example:** + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: ... + + # ==== how to run your application ==== + run: + # REQUIRED. Your Bun application start command + start: bun start + + # OPTIONAL. Define a health check with a HTTP GET request option. + # Configures the check on http://127.0.0.1:80/status + healthCheck: + httpGet: + port: 80 + path: /status +``` + +Read more about how the [health check works] in Zerops. + +#### exec + +Configures the health check to run a local command. +Following attributes are available: + +| Parameter | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **command** | Defines a local command to be run.
The command has access to the same [environment variables](bun/how-to/create#set-secret-environment-variables) as your Bun application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. | + +**Example:** + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: ... + + # ==== how to run your application ==== + run: + # REQUIRED. Your Bun application start command + start: bun start + + # OPTIONAL. Define a health check with a shell command. + healthCheck: + exec: + command: | + touch grass + rm -rf life + mv /outside/user /home/user +``` + +Read more about how the [health check works] in Zerops. + +### crontab + +_OPTIONAL._ Defines cron jobs. + +Setup cron jobs in the following format: + +```yaml +zerops: + # define hostname of your service + - setup: app + + # ==== how to run your application ==== + run: + crontab: + # REQUIRED. Sets the command to execute: + - command: "" + # REQUIRED. Sets the interval time to execute: + timing: "0 * * * *" +``` + +Read more about setting up [cron](/references/cron) in Zerops. + +## Deploy configuration + +### readiness check + +_OPTIONAL._ Defines a readiness check. Read more about how the [readiness check works](bun/how-to/deploy-process#readiness-checks) in Zerops. + +`readinessCheck` requires either one `httpGet` object or one `exec` object. + +#### httpGet + +Configures the readiness check to request a local URL using a http GET method. + +Following attributes are available: + +| Parameter | Description | +| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **port** | Defines the port of the HTTP GET request.
The readiness check will trigger a GET request on `http://127.0.0.1:{port}/{path}` | +| **path** | Defines the URL path of the HTTP GET request.
The readiness check will trigger a GET request on `http://127.0.0.1:{port}/{path}` | +| **host** | **Optional.** The readiness check is triggered from inside of your runtime container so it always uses the localhost (`127.0.0.1`). If you need to add a `host` to the request header, specify it in the `host` attribute. | +| **scheme** | **Optional.** The readiness check is triggered from inside of your runtime container so no https is required.
If your application requires a https request, set `scheme: https` | + +**Example:** + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: ... + + # ==== how to deploy your application ==== + deploy: + # OPTIONAL. Define a readiness check with a HTTP GET request option. + # Configures the check on http://127.0.0.1:80/status + readinessCheck: + httpGet: + port: 80 + path: /status + + # ==== how to run your application ==== + run: ... +``` + +Read more about how the [readiness check works](bun/how-to/deploy-process#readiness-checks) in Zerops. + +#### exec + +Configures the readiness check to run a local command. +Following attributes are available: + +| Parameter | Description | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **command** | Defines a local command to be run.
The command has access to the same [environment variables](bun/how-to/create#set-secret-environment-variables) as your Bun application.
A single string is required. If you need to run multiple commands create a shell script or, use a multiline format as in the example below. | + +**Example:** + +```yaml +zerops: + # hostname of your service + - setup: app + # ==== how to build your application ==== + build: ... + + # ==== how to deploy your application ==== + deploy: + # OPTIONAL. Define a readiness check with a HTTP GET request option. + # Configures the check on http://127.0.0.1:80/status + readinessCheck: + exec: + command: | + touch grass + rm -rf life + mv /outside/user /home/user +``` + +Read more about how the [readiness check works](bun/how-to/deploy-process#readiness-checks) in Zerops. + + + + +

+ image +

+ +## Description of the build process + +Zerops starts a temporary build container and performs following actions: + +1. Installs the build environment: + - Sets up base system and Go runtime + - Restores cached files if available (based on `build.cache` configuration) + - Validates cache against current `build.os`, `build.base`, and `build.prepareCommands` +2. Downloads your application source code from [GitHub ↗](https://www.github.com), [GitLab ↗](https://www.gitlab.com) or via [Zerops CLI](/references/cli) +3. Optionally [customizes the build environment](#customize-bun-build-environment) +4. Runs the build commands +5. Uploads the application artefact to the internal Zerops storage +6. Preserves specified files for future builds (based on `build.cache` configuration) +7. Optionally [customizes the runtime environment](/bun/how-to/customize-runtime) +8. [Deploys your application](/bun/how-to/deploy-process) + +The build container is automatically deleted after the build has finished or failed. + +## Cancel running build + +When you know that the running build is not correct and you want to cancel it, you can do it in Zerops GUI. Go to the service detail, open the list of running processes and click on the **Open pipeline detail** button. Then click on the **Cancel build** button. + +

+ image +

+ +:::caution +The build cancellation is available before the build pipeline is finished. When the build is finished, the deployment cannot be cancelled. +::: + +## Customize Bun build environment + +The default Bun build environment contains: + +- {data.alpine.default} +- selected version of Bun defined in `zerops.yaml` [build.base](bun/how-to/build-pipeline#base) parameter +- [zCLI](/references/cli), Zerops command line tool +- `npm`, `yarn`, `git` and `npx` tools + +If you prefer the Ubuntu OS instead of Alpine, set the [build.os](/bun/how-to/build-pipeline#os) attribute to `ubuntu`. To install additional packages or tools add one or more [build.prepareCommands](bun/how-to/build-pipeline#preparecommands) commands to your `zerops.yaml`. + +:::info +The application code is available in the `/var/www` folder in your build container before the prepare commands are triggered. This allows you to use any file from your application code in your prepare commands (e.g. a configuration file). +::: + +## Bun build hardware resources + +Build of your Bun application is run in a separate build container with following resource configuration: + +| HW resource | Minimum | Maximum | +| ------------- | ------- | ------- | +| **CPU cores** | 6 | 20 | +| **RAM** | 8 GB | 8 GB | +| **Disk** | 1 GB | 100 GB | + +The build container is always started with the minimum hardware resources and scales vertically up to the maximum resources. + +:::info +Hardware resources of the build containers are not charged. The build costs are covered by the standard Zerops [project fee](https://zerops.io/#pricing). +::: + +## Build time limit + +The time limit for the whole build pipeline is **1 hour**. After 1 hour, Zerops will terminate the build pipeline and delete the build container. + +## Troubleshooting build-related problems + +### Failure of a build prepare command + +If any [prepare command](bun/how-to/build-pipeline#preparecommands) fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](bun/how-to/logs#build-log) to troubleshoot the error. If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `prepareCommands` commands are finished, your custom build environment is ready for the build phase. + +### Invalidate the build cache +If you encounter unexpected build behavior or dependency issues, the problem might be related to [cached build data](/features/build-cache). While Zerops maintains the build cache to speed up deployments, sometimes you may need to start fresh. +To invalidate the build cache: + +1. Go to your service detail in Zerops GUI +2. Choose **Pipelines & CI/CD Settings** from the left menu +3. Click on the **Invalidate build cache** button + +This will force Zerops to run the next build clean, including all prepare commands, which can help resolve cache-related issues. After invalidation, your next build will also create a fresh cache. + +### Failure of a build command + +If any [build command](bun/how-to/build-pipeline#buildcommands) fails, it returns an exit code other than 0 and the build is canceled. Read the [build log](bun/how-to/logs#build-log) to troubleshoot the error. If the error log doesn't contain any specific error message, try to run your build with the `--verbose` option. + +```yaml +buildCommands: + - npm i --verbose + - npm run build +``` + +If the command ends successfully, it returns the exit code 0 and Zerops triggers the following command. When all `buildCommands` are finished, the application build is completed and ready for the [deploy](bun/how-to/deploy-process) phase. + + + +Zerops allows you to stop any service. Stopped services only consume disk. + +## Stop, start and restart Bun service in Zerops GUI + +To stop the Bun service in Zerops GUI go to the project dashboard and select the **Stop** menu item in the top right corner. + +{/*TODO screenshot (show menu with the start and stop items on a service)*/} + +To start the stopped Bun service choose the **Start** item from the same menu. + +To restart the Bun service choose the **Restart** item from the same menu. + +## Stop and start Bun using zCLI + +zCLI is the Zerops command-line tool. To stop and start the Bun service via the command-line, follow these steps: + +1. [Install & setup zCLI](/references/cli) +2. Run the `zcli service stop` command + +```sh +Usage: + zcli service stop [serviceIdOrName] [flags] + +Flags: + -h, --help the enable Zerops subdomain command. + --projectId string If you have access to more than one project, you must specify the project ID for which the + command is to be executed. + --serviceId string If you have access to more than one service, you must specify the service ID for which the + command is to be executed. +``` + +:::info +zCLI commands are interactive, when you press enter after `zcli service stop`, you will be given a list of your projects and services to choose from. +::: + +3. Run the `zcli service start` command + +```sh +Usage: + zcli service start [{serviceName | serviceId}] [flags] + +Flags: + -h, --help the service start command. + --projectId string If you have access to more than one project, you must specify the project ID for which the + command is to be executed. + --serviceId string If you have access to more than one service, you must specify the service ID for which the + command is to be executed. +``` + +:::info +zCLI commands are interactive, when you press enter after `zcli service start`, you will be given a list of your projects and services to choose from. +::: + + + + +Zerops provides a powerful Bun runtime service with extensive build support. The Bun runtime is highly scalable and customizable to suit your development and production needs. With just a few clicks or commands, you can have a production-ready Bun environment up and running in no time. + +## Create a Bun service using Zerops GUI + +First, set up a project in the Zerops GUI. Then go to the project dashboard page and choose **Add new service** in the left menu under the **Services** section. From there, you can add a new Bun service: + +