# Hostman Documentation — Full Text

> Complete text of the Hostman product documentation in Markdown. Each article below starts with an H1 heading followed by a link to its canonical page.

This file holds the entire documentation corpus. The text of a single section is available at /docs/<section>/llms-full.txt — see the section list at https://hostman.com/llms.txt
Index: https://hostman.com/llms.txt
Articles: 295
Last updated: 2026-10-08

# App Platform

Source: https://hostman.com/docs/app-platform/

[App Platform](https://hostman.com/app-platform/) is a container-based platform-as-a-service (PaaS) for building and running applications created with your preferred programming languages and frameworks.

Each backend application is a service that runs inside its own Docker container. 

This creates an abstraction layer that allows you to move beyond the server or cloud concept. Hostman also makes this concept transparent: for instance, you can see the hardware configuration, but you don't have to worry about setting up Nginx or obtaining an SSL certificate. We take care of all that for you.

Services communicate with each other using URLs via a global or private network. Hostman allows each service to be scaled in one click, so you can easily avoid bottlenecks when scaling the service under high load.

Hostman platform supports most popular frameworks and allows you to connect any repositories deployed on GitHub, GitLab or Bitbucket platforms.

# How It Works

Source: https://hostman.com/docs/app-platform/how-it-works/

When you connect your GitHub, GitLab or Bitbucket repository, Hostman does the following:

1.  **Sets up a cloud server** with all the necessary software, such as a web server, Docker service, and others. It also sets up all security and performance settings following best practices.
2.  **Pulls the code** from your GitHub, GitLab or Bitbucket repository.
3.  **Installs all dependencies** stored in special files, such as `requirements.txt` for Python or `package.json` for Node.JS.
4.  **Builds the code** and checks whether it was built correctly. It also provides you with a build log, which you can easily check if anything goes wrong during the build process.
5.  **Launches a Docker container** for backend apps with the necessary environment and runs your application inside it. For a frontend app, Hostman does not launch a container and instead creates a directory on the server where your application will be stored.
6.  **Creates a Hostman subdomain** for your application. You can use this domain for testing purposes or for requests inside the app, if it works for you. For production we recommend [using your own domain](https://hostman.com/docs/app-platform/domains/).
7.  **Configures Nginx** to proxy your domain to the application.
8.  **Installs a Let’s Encrypt SSL certificate** to make sure all the data is reliably protected. Hostman uses an SSL connection between all the services in its architecture.

When you push a new commit to your Git repository, the same cycle is repeated again: Hostman pulls the code, installs dependencies, builds the application, and so on. This includes launching a new Docker container, which will have no data from the previous container. This way we ensure a clean deployment.

Hostman will automatically deploy the changes if you leave the [autodeploy](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) option enabled.

# App Platform Billing

Source: https://hostman.com/docs/app-platform/billing/

Hostman App Platform supports several application types, and the billing model depends on the type of application you deploy.

For all application types, charges are applied hourly. 

## Frontend Application Billing

Frontend applications use a usage-based billing model: you pay only for the resources actually consumed.

All incoming HTTP requests to the application are billed, including requests for static assets such as stylesheets, scripts, images, and other resources. The request type and HTTP method do not affect billing.

Pricing is $5.50 per 1,000,000 requests (equivalent to $0.055 per 10,000 requests).

Each application is allocated 2 GB of NVMe storage, billed at an additional $0.10 per month.

### Request Limit

To prevent overspending, you can set a limit on the number of incoming requests. Once the limit is reached, the application is stopped and billing is halted.

To set a limit:

1.  Go to the **App Platform** section and select the required application.
2.  Open the **Settings** tab.
3.  Click **Set limit** in the **Incoming request limits** section.
4.  Enable the request limit and specify the maximum number of incoming requests.
5.  Click **Save**.

### Viewing Statistics

The **Dashboard** tab displays the current number of requests for the month, as well as charts for the following periods:

-   last hour
-   last 6 hours
-   last 24 hours
-   last 7 days 

## Backend and Docker Application Billing

Backend applications and applications deployed via Dockerfile, Docker Compose, or a Docker Hub image are always hosted on a cloud server.

When deploying such an application, you select a server configuration in the dashboard, and the cost of that configuration is displayed immediately. Billing is based solely on the selected server, no additional usage-based charges apply.

You can [upgrade the server configuration](https://hostman.com/docs/app-platform/managing-apps/#change-the-plan) to a higher tier at any time. Downgrading to a lower configuration is not possible.

# Connect Repositories

Source: https://hostman.com/docs/app-platform/connecting-repositories/

You can connect the repository with your application’s code to our [App Platform](https://hostman.com/paas/) when creating a new app in the Hostman dashboard.

App Platform supports GitLab, GitHub and Bitbucket repositories, as well as any repositories that can be accessed by URL, including Gitea, self-hosted GitLab, GitHub Enterprise repositories, etc.

## Connecting a Repository from GitHub, GitLab, or Bitbucket

To connect the repository:

1.  Go to the **App Platform** section and click **Create app**.
2.  Click on the platform icon.
3.  Log in to your account.
4.  Allow access to the required repositories.
5.  Select the repository for deployment in the Hostman dashboard.

If you're already logged into your GitHub, GitLab, or Bitbucket account, Hostman will automatically display the available repositories. All you have to do is select the one you need.

If you are logged in, but the required repository is not available:

1.  Open the repository dropdown menu and click **Add account**.
2.  Choose a platform.
3.  Log in if necessary.
4.  Select the required repositories and save the changes.

Then select the desired repository for deployment in the Hostman dashboard.

## Connecting a Repository via URL

You can connect any repository to App Platform that has an external HTTP or HTTPS address, including repositories from self-hosted GitLab, GitHub Enterprise, or repositories hosted by providers that we do not directly support (for example, Gitea).

The option can also be used for security purposes: if you do not want to give access to the entire Git account, you can only add a specific repository using a link.

> [!NOTE]
> Automatic deployment will not be available for repositories connected via URL. After updating the code, you will need to deploy the application manually selecting the desired commit. 

For public repositories, providing a URL is enough. 

For private repositories, you will need to provide login and password for the account or a token that is generated in the provider interface (GitLab, GitHub, etc.).

### Connect a Repository

You can connect the repository with URL when creating a new application:

1.  Go to the **App Platform** section and click **Create app**.
2.  Click **Connect the repository via URL**.
3.  Provide the URL to the repository and access details if the repository is private.
4.  Click **Connect**.

The repository and available commits will be displayed in the dashboard.

The connection link must be in Git URL format, for example:

```shell
https://github.com/hostman/app-example.git
```

In GitHub you can get the required link by clicking on **Code** → **HTTPS**.

The same in GitLab or Bitbucket: go to the desired repository → click on **Code**/**Clone** → **Clone with HTTPS**.

### Get a Token on GitHub

To generate a token in GitHub:

1.  Go to **Settings** → **Developer Settings** → **Personal access tokens** → **Tokens (classic)** → **Generate new token (classic)**.
2.  Set the token name, expiration date, and permissions. To work with private repositories, you need to select **repo**.
3.  Click **Generate token**.
4.  Copy the token and paste it into the **Password or token** field in the Hostman dashboard.

### Get a Token in GitLab

To connect GitLab repositories, you can use your account password or token generated in your GitLab account settings.

1.  Go to **Settings** → **Access Tokens**.
2.  Create a new token, specifying its name, expiration date, and permissions. At a minimum, you will need permission to read repositories.
3.  Click **Create personal access token**.
4.  Copy the token and paste it into the **Password or token** field in the Hostman dashboard.

### Getting a Link and Token in Bitbucket

To access a Bitbucket repository, you need to issue an API token.

1.  Go to your Atlassian **Account settings** → **Security** → [API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens). 
2.  Click **Create API Token with scopes**.
3.  Set the name and expiration date for the token. Click **Next**.
4.  Select **Bitbucket** and click **Next**.
5.  Select `read:repository:bitbucket` and click **Next**.
6.  Click **Create token**.
7.  Copy the token and paste it into the **Password or token** field in the Hostman dashboard.
8.  Go to the repository and click **Clone**. Copy everything that comes after `git clone` and paste it into the **Repository URL** field.
9.  Copy the part of the link between `https://` and `@` and paste it into the **Username** field.

## Removing Connected Repositories

Any added repository can be unlinked from App platform. 

> [!NOTE]
> If you unlink a repository, any deployments (both automatic and manual) of all applications created from this repository will become impossible.

1.  Go to the **App Platform** section and click **Create app**.
2.  Click on the drop-down list of repositories and click **Delete** next to the repository you wish to remove.
3.  Confirm the action.

## Troubleshooting

### App Platform Does Not Display the Repository

If your GitHub, GitLab or Bitbucket account is connected to App Platform, but the required repository is not displayed in the Hostman dashboard dashboard, there may be two reasons:

-   You added the repository after you had logged into your GitHub, GitLab, or Bitbucket account from App Platform.
-   You allowed access to only certain repositories, and the required repository is not selected.

To solve the problem:

1.  Go to the **App Platform** section and click **Create app**.
2.  Open the repository dropdown menu and click **Add account**.
3.  Choose a platform.
4.  Log in if necessary.
5.  Select the desired repository and save your changes.

Connected repositories will appear in the Hostman dashboard, and you can select the one you need.

# Deploy Frontend Apps

Source: https://hostman.com/docs/app-platform/frontend-apps/

To deploy a frontend application on Hostman, go to the [App Platform](https://hostman.com/my/apps) section and click **Create app**.

## Step 1. Connect Your Repository

You can connect a repository in one of two ways:

**From your GitHub, GitLab, or BitBucket account**

1.  Click on the platform name.
2.  Log in to your account.
3.  Select the desired repository in your Hostman dashboard.

If you are already logged in, Hostman will immediately show the available repositories. Choose the one you need.

**By URL**

You can connect any repository from any platform by providing its Git URL.

1.  Click **Connect the repository via URL**.
2.  Enter the Git URL of the repository. 
3.  If the repository is private, also enter the access details.

Read more about connecting repositories [here](https://hostman.com/docs/app-platform/connecting-repositories).

App Platform automatically detects your application's framework and runtime version from the repository, but you can change them manually if needed.

For [Nuxt](https://hostman.com/docs/app-platform/frontend-apps/nuxt/#ssr-support) and [Next.js](https://hostman.com/docs/app-platform/frontend-apps/nextjs/#ssr-support) apps, you can enable SSR support, which will allow you to choose a server configuration further on, as with [backend applications](https://hostman.com/docs/app-platform/backend-apps/).

## Step 2. Select Branch and Commit

**Branch**

Select a branch for deployment. 

The menu displays the 200 most recent branches, as well as the default branch (`master`, `main`, or `default`) if the repository is connected via GitHub, GitLab, or Bitbucket.

**Commit**

Leave the **Build by the last executed commit** option enabled if you want App Platform to deploy the latest commit and automatically rebuild the application when you add new commits to the repository. You can [disable automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) in the future.

If you want to select a specific commit, disable this option. Note that it will also disable automatic deployments.

## Step 3. Select Server Region and Configuration

**Region**

Select the region where your app will be deployed. 

**Configuration**

For frontend apps, server configuration cannot be customized. Each frontend application is allocated 2 GB of NVMe disk space. Applications are billed [based on resource usage](https://hostman.com/docs/app-platform/billing/).

If earlier you enabled SSR support for [Nuxt](https://hostman.com/docs/app-platform/frontend-apps/nuxt/#ssr-support) and [Next.js](https://hostman.com/docs/app-platform/frontend-apps/nextjs/#ssr-support) apps, select your server configuration. You will be able [upgrade](https://hostman.com/docs/app-platform/managing-apps/#change-the-plan) your server later, however, downgrading will not be possible.

## Step 4. **Configure Additional Settings**

Click **Show advanced settings** to configure additional parameters. 

Any of these settings can be [updated](https://hostman.com/docs/app-platform/deployments/#deploy-with-new-parameters) later, and you can redeploy the app with the new parameters. 

**Build Command**

The command used to build the application from the repository root. App Platform will automatically suggest a build command for your project. You can edit it if necessary, but in most cases no changes are required.

**Dependencies**

If you need additional system packages (for example, for building a project), specify them here. They will be passed to the `apt install` command. 

You can enter multiple dependencies separating them with spaces.

#### Build Directory

App Platform will automatically suggest a build directory for your project. In most cases no changes are required.

The **Build Directory** parameter does not change the directory from which the build command is executed. Instead, it specifies the path (relative to the repository root) to the directory that will contain the built artifacts, such as `index.html`.

If both **Build Directory** and **Project Directory Path** are specified, the final path used to serve the site files is constructed as:

```shell
/<Project Directory>/<Build Directory>
```

For example:

-   Project Directory: `/apps/frontend`
-   Build Directory: `/dist`

In this case, the files will be served from the `/apps/frontend/dist` directory.

#### Project Directory Path

By default, the build command runs from the root of the repository. If your project files, including `package.json`, are located in a subdirectory (for example, `/apps/frontend`), specify the path to that directory relative to the repository root in this field.

When a path is specified:

-   The working directory switches to the specified folder.
-   Dependencies are installed using the project files located in that folder.
-   Build and run commands are also executed from that folder.

**Environment Variables**

Use variables to store and pass configuration values such as passwords, file paths, and tokens. See more [here](https://hostman.com/docs/app-platform/variables/).

## Step 5. Enter App Information

Here you can specify a name and a comment for your application to be displayed in the Hostman dashboard. You can also select a project to add the app to.

These settings can also be changed later.

## Step 6. Deploy

Click **Create**. Once the process starts, you will see the deployment log on the **Deploy** tab.

The deploy log contains all the necessary information to solve possible issues. If something goes wrong, for example, due to errors in the code, the deploy log will display the notification about it specifying the cause of the problem.

When you first deploy a project, the server installation may take some time. Once the process is completed, the application status will be updated, and you will also see a message about this in the log.

All done!

You can find and copy your app’s URL (the technical domain that was linked to the app) on the main page of the **App Platform** section or in the **Settings** tab of your app. You can also [add your own domain](https://hostman.com/docs/app-platform/domains/) to the app.

The application will run on ports 443 and 80.

In the future, App Platform will monitor updates in the repository and, if [automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) is enabled, automatically rebuild the project with new changes.

# Deploy an Angular App

Source: https://hostman.com/docs/app-platform/frontend-apps/angular/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

> [!NOTE]
> For Angular versions **16 and below**, the default build output path does **not** include the `browser/` directory. Make sure to remove `browser/` from the build path when configuring the deployment.

When deploying an Angular project, the build environment runs the following commands by default:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*

npm install -g @angular/cli@latest
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

# Deploy an Ember App

Source: https://hostman.com/docs/app-platform/frontend-apps/ember/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

When deploying an Ember project, the build environment runs the following commands by default:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

# Deploy a Next.js App

Source: https://hostman.com/docs/app-platform/frontend-apps/nextjs/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

## Build Environment Setup

By default, the following commands are executed to build a Next.js project:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

## SSR Support

When creating an application, you can enable SSR support.

![05466c8f 91c4 47eb 826c 3deb7c6041e2](https://content.hostman.com/assets/163657f2-d38a-42d0-9711-8affb87fdbec.png?width=746&height=713)

In this case, the application will run [as a backend application](https://hostman.com/docs/app-platform/backend-apps/):

-   You will need to select a server configuration. 
-   The dashboard interface after deployment will be identical to that of a backend application.
-   You will be able to define a start command. The default start command is:

```
npm start
```

SSR support cannot be disabled after deployment. To change the application mode, you will need to create a new application with the desired configuration.

# Deploy a Nuxt App

Source: https://hostman.com/docs/app-platform/frontend-apps/nuxt/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

## Build Environment Setup

By default, the following commands are executed to build a Nuxt project:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

## SSR Support

When creating an application, you can enable SSR support.

![05466c8f 91c4 47eb 826c 3deb7c6041e2](https://content.hostman.com/assets/163657f2-d38a-42d0-9711-8affb87fdbec.png?width=746&height=713)

In this case, the application will run [as a backend application](https://hostman.com/docs/app-platform/backend-apps/):

-   You will need to select a server configuration.
-   The dashboard interface after deployment will be identical to that of a backend application.
-   You will be able to define a start command. The default start command is:

```shell
node .output/server/index.mjs
```

SSR support cannot be disabled after deployment. To change the application mode, you will need to create a new application with the desired configuration.

# Deploy a Preact App

Source: https://hostman.com/docs/app-platform/frontend-apps/preact/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

By default, the following commands are executed to build a Preact project:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

# Deploy a React App

Source: https://hostman.com/docs/app-platform/frontend-apps/react/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

By default, the following commands are executed to build a React project:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

# Deploy a Svelte App

Source: https://hostman.com/docs/app-platform/frontend-apps/svelte/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

By default, the following commands are executed to build a Svelte project:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

# Deploy a Vue App

Source: https://hostman.com/docs/app-platform/frontend-apps/vue/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

By default, the following commands are executed to build a Vue project:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

# Other JS Framework

Source: https://hostman.com/docs/app-platform/frontend-apps/other/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/frontend-apps/).

For projects built with any JavaScript framework, the following commands are executed by default:

```shell
DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y --no-install-recommends \
  curl \
  {% if system_dependencies %}{{ system_dependencies | join(' ') }}{% endif %} \
  && rm -rf /var/lib/apt/lists/*
```

Here, `system_dependencies` refers to the system packages configured in the dashboard.

After that, project dependencies are installed using the package manager detected in the repository (`yarn`, `pnpm`, or `npm`):

```shell
yarn install
pnpm install
npm install
```

# HTML/CSS/JS

Source: https://hostman.com/docs/app-platform/frontend-apps/static-website/

The **HTML/CSS/JS** runtime is designed for deploying pre-built frontend applications and static websites. It is suitable for projects generated with tools such as Hugo, Astro, VitePress, Jekyll, and similar static site generators.

Unlike applications built with frameworks such as Vue.js or React, App Platform does not build the application during deployment. Instead, it serves the pre-generated static assets directly from your repository.

## Preparing Your Project

Before deployment, build the project locally. The build process should generate a directory containing the static assets for your site, for example:

-   `dist`
-   `build`
-   `public`

The output directory must include an `index.html` file together with all required assets.

Example for Hugo:

```shell
hugo
```

After the build completes, the generated files will be available in the public directory.

## Deployment Behaviour

For HTML/CSS/JS applications, the following deployment options are not available:

-   Build command
-   Build directory
-   Dependency settings

This is because the application is treated as already compiled and does not require a build step during deployment.

## Project Directory

If the generated static files are located outside the repository root, specify the path to the directory containing the build output.

For example, if the compiled site is located in `/public`, use:

```shell
public
```

App Platform will then serve files directly from this directory.

# Deploy Backend Apps

Source: https://hostman.com/docs/app-platform/backend-apps/

To deploy a backend application on Hostman, go to the [App Platform](https://hostman.com/my/apps) section and click **Create app**.

## Step 1. Connect Your Repository

You can connect a repository in one of two ways:

**From your GitHub, GitLab, or BitBucket account**

1.  Click on the platform name.
2.  Log in to your account.
3.  Select the desired repository in your Hostman dashboard.

If you are already logged in, Hostman will immediately show the available repositories. Choose the one you need.

**By URL**

You can connect any repository from any platform by providing its Git URL.

1.  Click **Connect the repository via URL**.
2.  Enter the Git URL of the repository. 
3.  If the repository is private, also enter the access details.

Read more about connecting repositories [here](https://hostman.com/docs/app-platform/connecting-repositories).

App Platform automatically detects your application's framework and runtime version from the repository, but you can change them manually if needed.

## Step 2. Select Branch and Commit

**Branch**

Select a branch for deployment. 

The menu displays the 200 most recent branches, as well as the default branch (`master`, `main`, or `default`) if the repository is connected via GitHub, GitLab, or Bitbucket.

**Commit**

Leave the **Build by the last executed commit** option enabled if you want App Platform to deploy the latest commit and automatically rebuild the application when you add new commits to the repository. You can [disable automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) in the future.

If you want to select a specific commit, disable this option. Note that it will also disable automatic deployments.

## Step 3. Select Server Region and Configuration

**Region**

Your application must run on a separate cloud server. Select the region where the server should be located.

**Configuration**

Select the server configuration. You can always [upgrade](https://hostman.com/docs/app-platform/managing-apps/#change-the-plan) your server later, however, downgrading will not be possible.

## Step 4. **Configure Additional Settings**

Click **Show advanced settings** to configure additional parameters. 

> [!NOTE]
> Note: you can't change the private network once the app is deployed. Every other setting here can be [updated](https://hostman.com/docs/app-platform/deployments/#deploy-with-new-parameters) later, and you can redeploy the app with the new parameters. 

**Private Network**

You can add the application to a private network and specify the IP address the app will use.

Apps with a private IP address may experience a short downtime during redeployment, as existing ports need to be freed up before the new version starts.

**Build Command**

The command used to build the application from the repository root. Adjust it if necessary.

**Dependencies**

If you need additional system packages (for example, for building a project), specify them here. They will be passed to the `apt install` command. 

You can enter multiple dependencies separating them with spaces.

**Start Command**

In most cases, App Platform will automatically determine the start command for your project, so you can leave it unchanged.

**Project Directory Path**

If your project files are located in a subdirectory rather than in the repository root, specify the path to that directory in this field.

When a project directory path is specified:

-   The working directory switches to the specified folder.
-   Dependencies are installed using the project files located in that folder.
-   Build and run commands are also executed from that folder.

**Health Check Path**

App Platform uses the health check path to periodically verify that your application is running and functioning correctly. See more [here](https://hostman.com/docs/app-platform/healthcheck-path/).

**Environment Variables**

Use variables to store and pass configuration values such as passwords, file paths, and tokens. See more [here](https://hostman.com/docs/app-platform/variables/).

## Step 5. Enter the App Information

Here you can specify a name and a comment for your application to be displayed in the Hostman dashboard. You can also select a project to add the app to.

These settings can also be changed later.

## Step 6. Deploy

Click **Create**. Once the process starts, you will see the deployment log on the **Deploy** tab.

The deploy log contains all the necessary information to solve possible issues. If something goes wrong, for example, due to errors in the code, the deploy log will display the notification about it specifying the cause of the problem.

When you first deploy a project, the server installation may take some time. Once the process is completed, the application status will be updated, and you will also see a message about this in the log.

All done!

You can find the application's IP address and the technical domain linked to the app in the **Dashboard** tab. The application will be available on port 443; port 80 is also open.

To link your own domain to the app, follow [this guide](https://hostman.com/docs/app-platform/domains/).

In the future, App Platform will monitor updates in the repository and, if [automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) is enabled, automatically rebuild the project with new changes.

# Deploy a Phoenix App

Source: https://hostman.com/docs/app-platform/backend-apps/phoenix/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

Hostman uses the following environment when building a Phoenix application:

-   Elixir 1.15–1.19 (you can select the version when creating an App)
-   Erlang
-   inotify-tools

By default, we will execute the following commands during the build:

```shell
apt install -y elixir erlang inotify-tools --fix-missing
```

The default command used to run the application is:

```shell
mix phx.server
```

Make sure that:

-   The `mix.exs` file is located in the root of the project.
-   The file contains the correct configuration for your Phoenix application.

# Deploy a Beego App

Source: https://hostman.com/docs/app-platform/backend-apps/beego/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment to build a Beego application:

-   Go 1.22.1, 1.23, 1.24, or 1.25 (you can choose the version when creating the app)
-   Go Modules

By default, Hostman downloads dependencies with Go Modules based on your `go.mod` file. It then builds the application with the following command:

```shell
go build -o main .
```

This command compiles the package in the current directory into an executable named `main`.

The default start command is:

```shell
./main
```

## Requirements

Make sure the application listens on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

# Deploy an Echo App

Source: https://hostman.com/docs/app-platform/backend-apps/echo/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment to build an Echo application:

-   Go 1.22.1, 1.23, 1.24, or 1.25 (you can choose the version when creating the app)
-   Go Modules

By default, Hostman downloads dependencies with Go Modules based on your go.mod file. It then builds the application with the following command:

```shell
go build -o main .
```

This command compiles the package in the current directory into an executable named `main`.

The default start command is:

```shell
./main
```

## Requirements

-   Make sure the build directory contains a `go.mod` file that lists Echo and all other dependencies your project needs.
-   Make sure the build directory contains a `main` package with a `main()` function that starts the application server.
-   Make sure the application listens on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

# Deploy a Fiber App

Source: https://hostman.com/docs/app-platform/backend-apps/fiber/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/). 

## Application Build

Hostman builds your app in the following environment:

-   Go: versions 1.25, 1.24, 1.23, and 1.22.1 are available when you create an app.
-   Go Modules: used to manage dependencies.

By default, Hostman downloads dependencies with Go Modules based on your `go.mod` file. It then builds your app with this command:

```shell
go build -o main .
```

The command compiles the package in the current directory into an executable named `main`.

The default start command is:

```shell
./main
```

## Requirements

-   Make sure the build directory contains a `go.mod` file that lists Fiber and your other dependencies.
-   Make sure the build directory contains a `main` package with a `main()` function that starts your server.
-   Make sure your app listens on `0.0.0.0`, not `127.0.0.1`. Otherwise, external connections won't work.

# Deploy a Gin App

Source: https://hostman.com/docs/app-platform/backend-apps/gin/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment to build a Gin application:

-   Go 1.22.1, 1.23, 1.24, or 1.25 (you can choose the version when creating the app)
-   Go Modules

App Platform downloads dependencies with Go Modules based on your `go.mod` file and builds the application with the following command:

```shell
go build -o main .
```

This command compiles the package in the current directory into an executable named `main`.

The default start command is:

```shell
./main
```

## Requirements

Make sure the application listens on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

# Deploy a Micronaut App

Source: https://hostman.com/docs/app-platform/backend-apps/micronaut/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/). 

## Application Build

Hostman builds your app in the following environment:

-   **Java**: versions 8, 11, 17, 18, 19, 21, and 25 are available when you create an app.
-   **Maven**: used to build your app and manage dependencies.

By default, App Platform builds your app with this command:

```shell
mvn clean package
```

The default start command is:

```shell
java -jar app.jar
```

## Requirements

-   Make sure your project has a `pom.xml` file with the correct Micronaut dependencies and build settings.
-   Make sure the Java version you select is compatible with your project and your version of Micronaut.
-   Make sure your app listens on `0.0.0.0`, not `127.0.0.1`. Otherwise, external connections won't work.

# Deploy a Quarkus App

Source: https://hostman.com/docs/app-platform/backend-apps/quarkus/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment to build a Quarkus application:

-   Java 8, 11, 17, 18, 19, 21, or 25 (you can choose the version when creating the app)
-   Maven

The default build command is:

```shell
mvn clean package
```

The default start command is:

```shell
java -jar quarkus-run.jar
```

## Requirements

-   Make sure your project has a `pom.xml` file with the correct Quarkus dependencies and build settings.
-   Make sure the Java version you select is compatible with your project and your version of Quarkus.
-   Make sure the application listens on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

# Deploying a Spring App

Source: https://hostman.com/docs/app-platform/backend-apps/spring/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

Hostman uses the following environment when building a Spring application:

-   OpenJDK 8, 11, 17, 18, or 19
-   Maven

Hostman will execute the following commands during the build:

```shell
apt install -y openjdk-{{env_version}}-jre-headless maven
```

The default start command is:

```shell
mvn spring-boot:run
```

Make sure that:

-   Your project has the `pom.xml` file.
-   The `spring-boot-starter` dependency is correctly defined in `pom.xml`.

# Deploying a Ktor App

Source: https://hostman.com/docs/app-platform/backend-apps/ktor/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

This guide explains how to build and deploy a Ktor application on Hostman App Platform. It covers the build environment, JAR selection process, and the runtime requirements your application must meet for a successful deployment.

## Building the Application

The application is built using the following environment:

-   OpenJDK
-   Kotlin
-   Gradle

The build process runs in the root of the repository or in the directory specified in the **Project directory path** field.

If the project includes a `gradlew` file, the template uses Gradle Wrapper for the build process. If `gradlew` is not present, the system Gradle installation is used instead.

By default, the following build command is executed:

```shell
./gradlew buildFatJar --no-daemon
```

If Gradle Wrapper is not available, the following command is used instead:

```shell
gradle buildFatJar --no-daemon
```

## Selecting the JAR File to Run

After the build is completed, App Platform selects the JAR file to run using the following logic:

1.  If the `build/libs/` directory contains a file matching the `*-all.jar` pattern, that file is used. This is typically the fat JAR generated by Ktor.
2.  If no `*-all.jar` file is found, the platform uses the first `.jar` file found in the `build/libs/` directory.

Make sure the Ktor Gradle plugin is configured correctly and that the `buildFatJar` task is available in the project.

## Application Requirements

Make sure your application listens on `0.0.0.0` instead of `127.0.0.1`. Otherwise, external connections will not be able to reach the application.

# Deploying an ASP.NET App

Source: https://hostman.com/docs/app-platform/backend-apps/asp-net/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

Depending on the version you chose when creating the app, Hostman will use one of the following .NET versions during the application build:

-   .NET 8.0
-   .NET 9.0
-   .NET 10.0

By default, we will set the following environment variable when running the application:

```shell
ASPNETCORE_URLS=http://0.0.0.0:8080
```

It is required to properly forward the port and allow the application to run inside a container.

The default run command:

```shell
dotnet run
```

# Deploying an Express App

Source: https://hostman.com/docs/app-platform/backend-apps/express/

App Platform supports three runtimes for Express applications: **Node.js**, **Bun**, and **Deno**. Each runtime has its own package manager, build command, start command, and config file.

> [!NOTE]
> You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

### Node.js

Hostman uses the following environment when building an Express application:

-   Node.js: 20, 22, or 24
-   npm
-   yarn
-   PM2 (latest version)

The application is built in the repository root or in the directory specified in the **Project directory path** field.

Hostman will execute the following commands during the build:

```shell
apt install -y nodejs --fix-missing
npm install pm2@latest -g
npm install express
```

If the project includes a `package.json` file and uses `yarn`, we will also run:

```shell
apt-get remove -y cmdtest yarn
npm install --global yarn
cd /<DIRECTORY> && yarn install --check-files
```

In all other cases, if the a `package.json` file is present:

```shell
cd /<DIRECTORY> && npm install
```

`<DIRECTORY>` is the path to the directory with `package.json`.

The application is run using the PM2 process manager. The default start command is:

```shell
pm2 start --no-daemon app.js
```

The application initialization file (`app.js` in the example above) can be named `app.js`, `server.js`, `main.js`, or `index.js`. 

### Deno

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. The following Deno versions are available:

-   2.7.14
-   2.7.10
-   2.6.0

Deno apps don't require a separate build step. App Platform runs your app directly inside a Deno container, so `deno compile` isn't used in a typical deployment.

App Platform uses the following command to start your app:

```shell
deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts
```

Alternatively, the start command can be defined as a task:

```shell
deno task start
```

When App Platform runs `deno task start`, Deno executes the `start` task defined in `deno.json`. Define it like this:

```ts
"tasks": {
  "start": "deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts"
}
```

This example assumes your app entry point is `main.ts`. Update the path if your project uses a different file.

#### Permissions

Deno requires you to declare exactly which permissions your app needs. Pass the relevant flags when running your app:

-   `--allow-net`: outbound network requests
-   `--allow-read`: read access to the filesystem
-   `--allow-write`: write access to the filesystem
-   `--allow-env`: access to environment variables
-   `--allow-run`: spawn subprocesses
-   `--allow-ffi`: load native (FFI) libraries
-   `--allow-hrtime`: high-resolution timers
-   `--allow-sys`: read system info (OS, CPU, etc.)
-   `--allow-all` or `-A`: grant all permissions at once
-   `--watch`: restart the app automatically when files change

For example, if your app makes network requests, reads environment variables, and accesses the filesystem:

```shell
deno run --allow-net --allow-env --allow-read src/index.ts
```

### Bun

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. Bun is used as both the package manager and runtime.

To build your app, App Platform runs:

```shell
bun build
```

To start your app, App Platform runs:

```shell
bun run start
```

This executes the start script defined in your `package.json`. Point it to your app's entry file:

```ts
"scripts": {
  "start": "bun run src/main.ts"
}
```

This example assumes your app entry point is `src/main.ts`. Update the path if your project uses a different file.

## Troubleshooting

### Deployment fails

If there are problems with deployment, first check the deployment log. You will be able to determine at what point something went wrong.

Often the problems are related to the start command. When using Node.js, check that everything in your development environment works with `pm2`. Make sure that all modules required to run the application are present in the `package.json` file.

### Please add build instructions to your script section in package.json

The problem is that the Node.js `yarn build` command accesses the `package.json` file, and if the value of the build directive is not specified, an error occurs.

To fix this, you need to add the necessary directives to the `scripts` section of the `package.json` file. Read more about using `scripts` [here](https://docs.npmjs.com/cli/v10/using-npm/scripts).

# Deploying a Fastify App

Source: https://hostman.com/docs/app-platform/backend-apps/fastify/

App Platform supports three runtimes for Fastify applications: **Node.js**, **Bun**, and **Deno**. Each runtime has its own package manager, build command, start command, and config file.

> [!NOTE]
> You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

### Node.js

Hostman uses the following environment when building a Fastify application:

-   Node.js: 20, 22, or 24
-   npm
-   yarn

The application is built in the repository root or in the directory specified in the **Project directory path** field.

If the project includes a `package.json` file and uses `yarn`, we will run:

```shell
apt remove -y cmdtest yarn
npm install --global yarn
cd /<DIRECTORY> && yarn install --check-files
```

In all other cases, if the a `package.json` file is present:

```shell
cd /<DIRECTORY> && npm install
```

`<DIRECTORY>` is the path to the directory with `package.json`.

The default start command is:

```shell
npm run start
```

Make sure that the `start` command is defined in the `scripts` section of your `package.json`. For example:

```shell
"scripts": {
  "start": "fastify start -l info app.js"
}
```

### Deno

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. The following Deno versions are available:

-   2.7.14
-   2.7.10
-   2.6.0

Deno apps don't require a separate build step. App Platform runs your app directly inside a Deno container, so `deno compile` isn't used in a typical deployment.

App Platform uses the following command to start your app:

```shell
deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts
```

Alternatively, the start command can be defined as a task:

```shell
deno task start
```

When App Platform runs `deno task start`, Deno executes the `start` task defined in `deno.json`. Define it like this:

```ts
"tasks": {
  "start": "deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts"
}
```

This example assumes your app entry point is `main.ts`. Update the path if your project uses a different file.

#### Permissions

Deno requires you to declare exactly which permissions your app needs. Pass the relevant flags when running your app:

-   `--allow-net`: outbound network requests
-   `--allow-read`: read access to the filesystem
-   `--allow-write`: write access to the filesystem
-   `--allow-env`: access to environment variables
-   `--allow-run`: spawn subprocesses
-   `--allow-ffi`: load native (FFI) libraries
-   `--allow-hrtime`: high-resolution timers
-   `--allow-sys`: read system info (OS, CPU, etc.)
-   `--allow-all` or `-A`: grant all permissions at once
-   `--watch`: restart the app automatically when files change

For example, if your app makes network requests, reads environment variables, and accesses the filesystem:

```shell
deno run --allow-net --allow-env --allow-read src/index.ts
```

### Bun

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. Bun is used as both the package manager and runtime.

To build your app, App Platform runs:

```shell
bun build
```

To start your app, App Platform runs:

```shell
bun run start
```

This executes the start script defined in your `package.json`. Point it to your app's entry file:

```ts
"scripts": {
  "start": "bun run src/main.ts"
}
```

This example assumes your app entry point is `src/main.ts`. Update the path if your project uses a different file.

## Troubleshooting

### Deployment fails

If there are problems with deployment, first check the deployment log. You will be able to determine at what point something went wrong.

Often the problems are related to the start command. Make sure that all modules required to run the application are present in the `package.json` file.

### Please add build instructions to your script section in package.json

The problem is that the build command accesses the `package.json` file, and if the value of the `build` directive is not specified, an error occurs.

To fix this, you need to add the necessary directives to the `scripts` section of the `package.json` file. Read more about using `scripts` [here](https://docs.npmjs.com/cli/v10/using-npm/scripts).

# Deploying a Hapi App

Source: https://hostman.com/docs/app-platform/backend-apps/hapi/

App Platform supports three runtimes for Hapi applications: **Node.js**, **Bun**, and **Deno**. Each runtime has its own package manager, build command, start command, and config file.

> [!NOTE]
> You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

### Node.js

Hostman uses the following environment when building a Hapi application:

-   Node.js: 20, 22, or 24
-   npm
-   yarn
-   PM2 (latest version)

The application is built in the repository root or in the directory specified in the **Project directory path** field.

Hostman will execute the following commands during the build:

```shell
apt install -y nodejs --fix-missing
npm install pm2@latest -g
npm install hapi @hapi/hapi
```

If the project includes a `package.json` file and uses `yarn`, we will also run:

```shell
apt-get remove -y cmdtest yarn
npm install --global yarn
cd /<DIRECTORY> && yarn install --check-files
```

In all other cases, if the a `package.json` file is present:

```shell
cd /<DIRECTORY> && npm install
```

`<DIRECTORY>` is the path to the directory with `package.json`. 

The application is run using the PM2 process manager. The default start command is:

```shell
pm2 start --no-daemon app.js
```

The application initialization file (`app.js` in the example above) can be named `app.js`, `server.js`, `main.js`, or `index.js`. 

### Deno

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. The following Deno versions are available:

-   2.7.14
-   2.7.10
-   2.6.0

Deno apps don't require a separate build step. App Platform runs your app directly inside a Deno container, so `deno compile` isn't used in a typical deployment.

App Platform uses the following command to start your app:

```shell
deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts
```

Alternatively, the start command can be defined as a task:

```shell
deno task start
```

When App Platform runs `deno task start`, Deno executes the `start` task defined in `deno.json`. Define it like this:

```ts
"tasks": {
  "start": "deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts"
}
```

This example assumes your app entry point is `main.ts`. Update the path if your project uses a different file.

#### Permissions

Deno requires you to declare exactly which permissions your app needs. Pass the relevant flags when running your app:

-   `--allow-net`: outbound network requests
-   `--allow-read`: read access to the filesystem
-   `--allow-write`: write access to the filesystem
-   `--allow-env`: access to environment variables
-   `--allow-run`: spawn subprocesses
-   `--allow-ffi`: load native (FFI) libraries
-   `--allow-hrtime`: high-resolution timers
-   `--allow-sys`: read system info (OS, CPU, etc.)
-   `--allow-all` or `-A`: grant all permissions at once
-   `--watch`: restart the app automatically when files change

For example, if your app makes network requests, reads environment variables, and accesses the filesystem:

```shell
deno run --allow-net --allow-env --allow-read src/index.ts
```

### Bun

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. Bun is used as both the package manager and runtime.

To build your app, App Platform runs:

```shell
bun build
```

To start your app, App Platform runs:

```shell
bun run start
```

This executes the start script defined in your `package.json`. Point it to your app's entry file:

```ts
"scripts": {
  "start": "bun run src/main.ts"
}
```

This example assumes your app entry point is `src/main.ts`. Update the path if your project uses a different file.

## Troubleshooting

### Deployment fails

If there are problems with deployment, first check the deployment log. You will be able to determine at what point something went wrong.

Often the problems are related to the start command. If using Node.js, check that everything in your development environment works with `pm2`. Make sure that all modules required to run the application are present in the `package.json` file.

### Please add build instructions to your script section in package.json

The problem is that the Node.js `yarn build` command accesses the `package.json` file, and if the value of the build directive is not specified, an error occurs.

To fix this, you need to add the necessary directives to the `scripts` section of the `package.json` file. Read more about using `scripts` [here](https://docs.npmjs.com/cli/v10/using-npm/scripts).

# Deploying a Nest App

Source: https://hostman.com/docs/app-platform/backend-apps/nest/

App Platform supports three runtimes for Nest applications: **Node.js**, **Bun**, and **Deno**. Each runtime has its own package manager, build command, start command, and config file.

> [!NOTE]
> You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

### Node.js

Hostman uses the following environment when building a Nest application:

-   Node.js: 20, 22, or 24
-   npm
-   yarn

The application is built in the repository root or in the directory specified in the **Project directory path** field.

If the project has a `package.json` file and uses `yarn`, we will run:

```shell
apt remove -y cmdtest yarn
npm install --global yarn
cd /<DIRECTORY> && yarn install --check-files
```

In all other cases, if the a `package.json` file is present:

```shell
cd /<DIRECTORY> && npm install
```

`<DIRECTORY>` is the path to the directory with `package.json`. 

The default start command is:

```
npm run start:prod
```

Make sure that the `start:prod` command is defined in the `scripts` section of your `package.json`. For example:

```shell
"scripts": {
  "start:prod": "node dist/main.js"
}
```

### Deno

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. The following Deno versions are available:

-   2.7.14
-   2.7.10
-   2.6.0

Deno apps don't require a separate build step. App Platform runs your app directly inside a Deno container, so `deno compile` isn't used in a typical deployment.

App Platform uses the following command to start your app:

```shell
deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts
```

Alternatively, the start command can be defined as a task:

```shell
deno task start
```

When App Platform runs `deno task start`, Deno executes the `start` task defined in `deno.json`. Define it like this:

```ts
"tasks": {
  "start": "deno run --allow-net --allow-env --allow-read --allow-sys --allow-ffi main.ts"
}
```

This example assumes your app entry point is `main.ts`. Update the path if your project uses a different file.

#### Permissions

Deno requires you to declare exactly which permissions your app needs. Pass the relevant flags when running your app:

-   `--allow-net`: outbound network requests
-   `--allow-read`: read access to the filesystem
-   `--allow-write`: write access to the filesystem
-   `--allow-env`: access to environment variables
-   `--allow-run`: spawn subprocesses
-   `--allow-ffi`: load native (FFI) libraries
-   `--allow-hrtime`: high-resolution timers
-   `--allow-sys`: read system info (OS, CPU, etc.)
-   `--allow-all` or `-A`: grant all permissions at once
-   `--watch`: restart the app automatically when files change

For example, if your app makes network requests, reads environment variables, and accesses the filesystem:

```shell
deno run --allow-net --allow-env --allow-read src/index.ts
```

### Bun

App Platform builds your app in the repository root, or in the directory you specify in the **Project directory path** field. Bun is used as both the package manager and runtime.

To build your app, App Platform runs:

```shell
bun build
```

To start your app, App Platform runs:

```shell
bun run start
```

This executes the start script defined in your `package.json`. Point it to your app's entry file:

```ts
"scripts": {
  "start": "bun run src/main.ts"
}
```

This example assumes your app entry point is `src/main.ts`. Update the path if your project uses a different file.

## Troubleshooting

### Deployment fails

If there are problems with deployment, first check the deployment log. You will be able to determine at what point something went wrong.

Often the problems are related to the start command. Make sure that all modules required to run the application are present in the `package.json` file.

### Please add build instructions to your script section in package.json

The problem is that the Node.js `npm run build` command accesses the `package.json` file, and if the value of the `build` directive is not specified, an error occurs.

To fix this, you need to add the necessary directives to the `scripts` section of the `package.json` file. Read more about using `scripts` [here](https://docs.npmjs.com/cli/v10/using-npm/scripts).

# Deploying a Laravel App

Source: https://hostman.com/docs/app-platform/backend-apps/laravel/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

Hostman uses the following environment when building a Laravel application:

-   PHP: 8.2, 8.3, 8.4, or 8.5, depending on the version you chose when creating the app
-   Composer

The default start command is:

```shell
php artisan serve --host=0.0.0.0 --port=8000
```

After the deployment, Hostman will automatically issue an SSL certificate and configure the app to work over HTTPS. However, Laravel may continue to generate HTTP links by default, which can cause errors when making AJAX requests or submitting forms.

To force HTTPS, add the following code to the `app/Providers/AppServiceProvider.php` file:

```php
public function boot()
{
    URL::forceScheme('https');
}
```

# Deploying a Symfony App

Source: https://hostman.com/docs/app-platform/backend-apps/symfony/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

Hostman uses the following environment when building a Symfony application:

-   PHP: 8.2, 8.3, 8.4, or 8.5, depending on the version you chose when creating the app
-   Composer
-   Symfony CLI (installed automatically)

The default start command is:

```shell
symfony server:start
```

Make sure that:

-   Your project has the `symfony.lock` file.
-   Environment variables and `.env` files are properly configured.

# Deploying a Yii App

Source: https://hostman.com/docs/app-platform/backend-apps/yii/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

Hostman uses the following environment when building a Yii application:

-   PHP: 8.2, 8.3, 8.4, or 8.5, depending on the version you chose when creating the app
-   Composer

The default start command is:

```php
php yii serve 0.0.0.0
```

# Deploying an aiohttp App

Source: https://hostman.com/docs/app-platform/backend-apps/aiohttp/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment to build an aiohttp application:

-   Python 3.10–3.14 (you can choose the version when creating the app)
-   `pip`

By default, Hostman runs the following commands to prepare the build environment:

```shell
apt-get install -y --no-install-recommends curl build-essential libpq-dev
pip install --upgrade pip
pip install aiohttp
```

The default build command then installs your project's dependencies:

```shell
pip install --upgrade -r requirements.txt
```

The default start command is:

```shell
python3 main.py
```

## Requirements

-   Make sure `requirements.txt` lists `aiohttp` and all other dependencies your project needs.
-   Make sure your project's entry point is named `main.py` and starts the application server.
-   Make sure the application listens on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

# Deploying a Celery App

Source: https://hostman.com/docs/app-platform/backend-apps/celery/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment when building a Celery application:

-   Python 3.10, 3.11, 3.12, 3.13, or 3.14
-   `pip`
-   `gunicorn`
-   System libraries for working with PostgreSQL and MySQL

Hostman will execute the following commands during the build:

```shell
apt-get install -y python3 python3-pip gunicorn python3-psycopg2 libpq-dev python-dev default-mysql-client python3-dev default-libmysqlclient-dev python3-mysqldb --fix-missing
pip3 install psycopg2 
ln /usr/bin/python3 /usr/bin/python -sf
ln /usr/bin/pip3 /usr/bin/pip -sf
pip3 install celery
```

To install dependencies, add the following line to the build command:

```shell
pip3 install --upgrade -r requirements.txt
```

The default start command is:

```shell
celery -A tasks worker --loglevel=INFO
```

## Requirements

-   Make sure the application initialization file is named `main.py`.
-   Make sure the application is listening on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

## Troubleshooting

### Deployment fails

If there are problems with deployment, first check the deployment log. You will be able to determine at what point something went wrong.

Often the problems are related to the start command. Check that everything in your development environment works with `gunicorn`. Make sure that all modules required to run the application are present in the `requirements.txt` file.

# Deploying a Django App

Source: https://hostman.com/docs/app-platform/backend-apps/django/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment when building a Django application:

-   Python 3.10, 3.11, 3.12, 3.13, or 3.14
-   `pip`
-   `gunicorn`
-   System libraries for working with PostgreSQL and MySQL

Hostman will execute the following commands during the build:

```shell
apt-get install -y python3 python3-pip gunicorn python3-psycopg2 libpq-dev python-dev default-mysql-client python3-dev default-libmysqlclient-dev python3-mysqldb --fix-missing
pip3 install psycopg2 django
ln /usr/bin/python3 /usr/bin/python -sf
ln /usr/bin/pip3 /usr/bin/pip -sf
```

To install dependencies, add the following line to the build command:

```shell
pip3 install --upgrade -r requirements.txt
```

The default start command is:

```shell
python3 manage.py runserver 0.0.0.0:8000
```

You can also define environment variables. For example, to specify the hosts from which Django is allowed to receive requests, set the `DJANGO_ALLOWED_HOSTS` key with a value containing IP addresses or hostnames. You can specify multiple hosts, separated by commas without spaces. By default, this variable is set to `127.0.0.1,localhost`.

For more details on configuration, refer to the [Django documentation](https://docs.djangoproject.com/en/5.2/ref/settings/).

## Requirements

-   Make sure that the `manage.py` file is located in the root of the project and is used as the application's entry point.
-   Make sure to set `DEBUG=True` in the settings; otherwise, static files will not be served.
-   Make sure the application is listening on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

## Troubleshooting

### Deployment fails

If there are problems with deployment, first check the deployment log. You will be able to determine at what point something went wrong.

Often the problems are related to the start command. Check that everything in your development environment works with `gunicorn`. Make sure that all modules required to run the application are present in the `requirements.txt` file.

### DisallowedHost at /Invalid HTTP\_HOST

The problem occurs when the hostname is not specified in the `settings.py` file.

This setting is a security measure to prevent HTTP Host header attacks.

To fix the problem, you need to make changes to the `settings.py` file, specifying your domain in the `ALLOWED_HOSTS` directive, for example:

```shell
ALLOWED_HOSTS = ["your.domain.com"]
```

You can also allow all domains if you don't want to use this security measure:

```shell
ALLOWED_HOSTS = ["*"]
```

# Deploying a FastAPI App

Source: https://hostman.com/docs/app-platform/backend-apps/fastapi/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment when building a FastAPI application:

-   Python 3.10, 3.11, 3.12, 3.13, or 3.14 (you can select the version when creating an app)
-   `pip`
-   `uvicorn`

Hostman will execute the following commands during the build:

```shell
apt install -y p--no-install-recommends curl build-essential libpq-dev
pip install --upgrade pip
pip install fastapi uvicorn
```

To install dependencies, add the following line to the build command:

```shell
pip3 install --upgrade -r requirements.txt
```

The default start command is:

```shell
uvicorn main:app --host 0.0.0.0
```

If necessary, you can specify a port, for example:

```shell
uvicorn main:app --host 0.0.0.0 --port 80
```

## Requirements

-   Make sure the application initialization file is named `main.py`.
-   Make sure the application is listening on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

# Deploying a Flask App

Source: https://hostman.com/docs/app-platform/backend-apps/flask/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment when building a Flask application:

-   Python 3.10, 3.11, 3.12, 3.13, or 3.14
-   `pip`
-   `gunicorn`
-   System libraries for working with PostgreSQL and MySQL

Hostman will execute the following commands during the build:

```shell
apt install -y python3 python3-pip gunicorn python3-psycopg2 libpq-dev python-dev default-mysql-client python3-dev default-libmysqlclient-dev python3-mysqldb --fix-missing
pip3 install psycopg2 flask
ln /usr/bin/python3 /usr/bin/python -sf
ln /usr/bin/pip3 /usr/bin/pip -sf
```

To install dependencies, add the following line to the build command:

```shell
pip3 install --upgrade -r requirements.txt
```

For the app to deploy correctly, you may need to modify the start command to suit your project, specifying port binding, for example:

```
gunicorn main:app --timeout 60 --bind 0.0.0.0:80
```

## Requirements

-   Make sure the application initialization file (your app entry point) is named `main.py`.
-   Make sure the application is listening on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

## Troubleshooting

### Deployment fails

If there are problems with deployment, first check the deployment log. You will be able to determine at what point something went wrong.

Most errors are usually related to:

-   Missing `main.py` file or the `app` variable
-   Incorrect start command
-   Missing dependencies in `requirements.txt`

Make sure that the `gunicorn main:app` command runs successfully in your local environment.

# Deploying a Tornado App

Source: https://hostman.com/docs/app-platform/backend-apps/tornado/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

## Application Build

Hostman uses the following environment to build a Tornado application:

-   Python 3.10–3.14 (you can choose the version when creating the app)
-   `pip`

By default, Hostman runs the following commands to prepare the build environment: 

```shell
apt-get install -y --no-install-recommends curl build-essential libpq-dev
pip install --upgrade pip
pip install tornado
```

The default build command then installs your project's dependencies:

```shell
pip install --upgrade -r requirements.txt
```

The default start command is:

```shell
python3 main.py
```

## Requirements

-   Make sure `requirements.txt` lists Tornado and all other dependencies your project needs.
-   Make sure your project's entry point is named `main.py` and starts the application server.
-   Make sure the application listens on `0.0.0.0` rather than `127.0.0.1`; otherwise, external connections will not work.

# Deploying an Actix App

Source: https://hostman.com/docs/app-platform/backend-apps/actix/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

This guide covers the build process, binary selection logic, and the runtime requirements your Actix application must meet to be successfully deployed on Hostman App Platform.

## Building the Application

The application is built using the following environment:

-   Rust
-   Cargo

The build process runs in the root of the repository or in the directory specified in the **Project directory path** field.

The template uses a multi-stage build process. During the first stage, the application binary is compiled in release mode. During the second stage, the final runtime image starts the compiled application.

By default, the following build command is executed:

```shell
cargo build --locked --release
```

Make sure your project includes a valid `Cargo.toml` file with all required dependencies correctly defined.

The `--locked` flag forces Cargo to use dependency versions from `Cargo.lock`. Ensure that the `Cargo.lock` file is up to date and committed to the repository.

If your application requires additional system packages during the build process, such as OpenSSL libraries, specify them in the **Dependencies** field. These packages are installed before the `cargo build` command runs.

## Selecting the Binary to Run

After the build is completed, App Platform selects the binary to run using the following logic:

1.  If the build command explicitly includes the `--bin <name>` or `--bin=<name>` flag, that binary is used.
2.  If the `--bin` flag is not provided, the template attempts to detect the binary using the `default-run` value from `Cargo.toml` through `cargo metadata`.
3.  If `default-run` is not defined, the template scans the `target/release` directory.
4.  If exactly one executable binary is found, it is selected automatically.
5.  If multiple executable binaries are found, the build fails with an error. In this case, specify the binary explicitly in the build command:

```shell
cargo build --locked --release --bin <name>
```

## Application Requirements

Make sure your application listens on `0.0.0.0` instead of `127.0.0.1`. Otherwise, external connections will not be able to reach the application.

# Deploying an Axum App

Source: https://hostman.com/docs/app-platform/backend-apps/axum/

You can find the step-by-step deployment guide [here](https://hostman.com/docs/app-platform/backend-apps/).

This guide covers the build process and explains how the Hostman App Platform selects the runtime binary and what requirements your Axum application must meet before deployment.

## Building the Application

The application is built using the following environment:

-   Rust
-   Cargo

The build process runs in the root of the repository or in the directory specified in the **Project directory path** field.

The template uses a multi-stage build process. During the first stage, the application binary is compiled in release mode. During the second stage, the final runtime image starts the compiled application.

By default, the following build command is executed:

```shell
cargo build --locked --release
```

Make sure your project includes a valid `Cargo.toml` file with all required dependencies correctly defined.

The `--locked` flag forces Cargo to use dependency versions from `Cargo.lock`. Ensure that the `Cargo.lock` file is up to date and committed to the repository.

If your application requires additional system packages during the build process, such as OpenSSL libraries, specify them in the **Dependencies** field. These packages are installed before the `cargo build` command runs.

## Selecting the Binary to Run

After the build is completed, App Platform selects the runtime binary using the following logic:

1.  If the build command explicitly includes the `--bin <name>` or `--bin=<name>` flag, that binary is used.
2.  If the `--bin` flag is not provided, the template attempts to detect the binary using the `default-run` value from `Cargo.toml` through `cargo metadata`.
3.  If `default-run` is not defined, the template scans the `target/release` directory.
4.  If exactly one executable binary is found, it is selected automatically.
5.  If multiple executable binaries are found, the build fails with an error. In this case, specify the binary explicitly in the build command:

```shell
cargo build --locked --release --bin <name>
```

## Application Requirements

Make sure your application listens on `0.0.0.0` instead of `127.0.0.1`. Otherwise, external connections will not be able to reach the application.

# Deploy with a Dockerfile

Source: https://hostman.com/docs/app-platform/dockerfile/

Using Dockerfile, you can deploy any application on App Platform regardless of the framework used to build the app.

## Requirements

-   The Dockerfile can be located either in the repository root or in the directory specified in the **Project Directory Path** field. The Dockerfile must contain the instructions required to build and run the application.
-   You must specify the `EXPOSE` parameter in the Dockerfile so that Hostman can determine which port Nginx should listen on. If `EXPOSE` is not set, Nginx will listen on container port 8080 by default.
    

Example:

```shell
FROM python:3.6
MAINTAINER Name Name "mail@mail.com"
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
ENTRYPOINT ["python"]
CMD ["app.py"]
EXPOSE 3478
```

-   You can set environment variables in the Dockerfile or in the Hostman dashboard when creating a new app.
    

## Step 1. Connect Your Repository

You can connect a repository in one of two ways:

**From your GitHub, GitLab, or BitBucket account**

1.  Click on the platform name.
2.  Log in to your account.
3.  Select the desired repository in your Hostman dashboard.

If you are already logged in, Hostman will immediately show the available repositories. Choose the one you need.

**By URL**

You can connect any repository from any platform by providing its Git URL.

1.  Click **Connect the repository via URL**.
2.  Enter the Git URL of the repository. 
3.  If the repository is private, also enter the access details.

Read more about connecting repositories [here](https://hostman.com/docs/app-platform/connecting-repositories).

Make sure that the Framework field shows the **Dockerfile** option.

## Step 2. Select Branch and Commit

**Branch**

Select a branch for deployment. 

The menu displays the 200 most recent branches, as well as the default branch (`master`, `main`, or `default`) if the repository is connected via GitHub, GitLab, or Bitbucket.

**Commit**

Leave the **Build by the last executed commit** option enabled if you want App Platform to deploy the latest commit and automatically rebuild the application when you add new commits to the repository. You can [disable automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) in the future.

If you want to select a specific commit, disable this option. Note that it will also disable automatic deployments.

## Step 3. Select Server Region and Configuration

**Region**

Your application must run on a separate cloud server. Select the region where the server should be located.

**Configuration**

Select the server configuration. You can always [upgrade](https://hostman.com/docs/app-platform/managing-apps/#change-the-plan) your server later, however, downgrading will not be possible.

## Step 4. Configure **Additional Settings**

Click **Show advanced settings** to configure additional parameters. 

App Platform reads the parameters set in the Dockerfile and builds the application accordingly. 

Here you can also add the app to a private network, specify the project directory path, and set up the [health check path](https://hostman.com/docs/app-platform/healthcheck-path/) and [environment variables](https://hostman.com/docs/app-platform/variables/). If the health check or variables are already defined in the Dockerfile, there's no need to duplicate them here.

> [!NOTE]
> Note: you can't change the private network once the app is deployed. Every other setting here can be [updated](https://hostman.com/docs/app-platform/deployments/#deploy-with-new-parameters) later, and you can redeploy the app with the new parameters. 

**Private Network**

You can add the application to a private network and specify the IP address the app will use.

Apps with a private IP address may experience a short downtime during redeployment, as existing ports need to be freed up before the new version starts.

**Project Directory Path**

If the Dockerfile is located in the repository root, leave the **Project Directory Path** field empty.

If the Dockerfile is located in a subdirectory, specify the path to that directory relative to the repository root. This path is used both as the location of the Dockerfile and as the build context.

**Health Check Path**

App Platform uses the health check path to periodically verify that your application is running and functioning correctly. 

See more [here](https://hostman.com/docs/app-platform/healthcheck-path/).

**Environment Variables**

Use variables to store and pass configuration values such as passwords, file paths, and tokens. 

See more [here](https://hostman.com/docs/app-platform/variables/).

## Step 5. Enter the App Information

Here you can specify a name and a comment for your application to be displayed in the Hostman dashboard. You can also select a project to add the app to.

These settings can also be changed later.

## Step 6. Deploy

Click **Create**. Once the process starts, you will see the deployment log on the **Deploy** tab.

The deploy log contains all the necessary information to solve possible issues. If something goes wrong, for example, due to errors in the code, the deploy log will display the notification about it specifying the cause of the problem.

When you first deploy a project, the server installation may take some time. Once the process is completed, the application status will be updated, and you will also see a message about this in the log.

All done!

You can find the application's IP address and the technical domain linked to the app in the **Dashboard** tab. To link your own domain to the app, follow [this guide](https://hostman.com/docs/app-platform/domains/).

The application runs on ports 80 and 443.

In the future, App Platform will monitor updates in the repository and, if [automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) is enabled, automatically rebuild the project with new changes.

# Deploy with Docker Compose

Source: https://hostman.com/docs/app-platform/docker-compose/

App Platform allows you to deploy an application using a Docker Compose file located in the repository. This enables running any type of application, including those built with frontend and backend frameworks not directly supported by the service.

## Requirements

### File Location

The `Dockerfile` and `docker-compose.yml` file must be located in the root of the connected repository. If the `Dockerfile` is located elsewhere, its path must be explicitly specified in the `docker-compose.yml` manifest. For example:

```yaml
services:
  app:
    build:
      context: ./app                        # Path to the application source code
      dockerfile: ./docker/Dockerfile.prod  # Explicit path to the Dockerfile
```

### Reserved Ports

Do not use ports 80 and 443 as host ports in the manifest. These ports are reserved for Nginx.

### Proxying

Proxying is configured for the first service listed in `docker-compose.yml`. Other services, if they have host ports defined, will be accessible only via those explicit ports. For example:

```
services:
  my-app:
    ports:
      - "9000:80"
  adminer:
    ports:
      - "8080:8080"
```

In this case, `my-app` will be available at the main domain, and `adminer` will be available at `http://<domain>:8080`.

### Restrictions on docker-compose.yml

The following restrictions apply to `docker-compose.yml`. Attempting to deploy a manifest containing any of these directives or parameters will result in an error.

#### Disallowed directives

The following directives cannot be used in `docker-compose.yml`:

-   `cap_add`
-   `cgroup`
-   `cgroup_parent`
-   `device_cgroup_rules`
-   `devices`
-   `extends`
-   `extra_hosts`
-   `include`
-   `ipc`
-   `network_mode: container:...`
-   `pid`
-   `privileged`
-   `security_opt`
-   `sysctls`
-   `use_api_socket`
-   `userns_mode`
-   `uts`
-   `volumes`
-   `volumes_from`

#### Disallowed parameters

The following parameters are prohibited:

-   `external` in the `volumes`, `networks`, `configs`, and `secrets` sections
-   `driver_opts`
-   `name`

#### Path traversal

Path traversal outside the allowed directory in the `file` value for `configs` and `secrets` is prohibited.

### Network Mode

The `host` network mode is not supported when configuring networking.

## Step 1. Connect Your Repository

You can connect a repository in one of two ways:

**From your GitHub, GitLab, or BitBucket account**

1.  Click on the platform name.
2.  Log in to your account.
3.  Select the desired repository in your Hostman dashboard.

If you are already logged in, Hostman will immediately show the available repositories. Choose the one you need.

**By URL**

You can connect any repository from any platform by providing its Git URL.

1.  Click **Connect the repository via URL**.
2.  Enter the Git URL of the repository. 
3.  If the repository is private, also enter the access details.

Read more about connecting repositories [here](https://hostman.com/docs/app-platform/connecting-repositories).

> [!NOTE]
> Make sure that the **Framework** field shows the **Docker Compose** option.

## Step 2. Select Branch and Commit

**Branch**

Select a branch for deployment. 

The menu displays the 200 most recent branches, as well as the default branch (`master`, `main`, or `default`) if the repository is connected via GitHub, GitLab, or Bitbucket.

**Commit**

Leave the **Build by the last executed commit** option enabled if you want App Platform to deploy the latest commit and automatically rebuild the application when you add new commits to the repository. You can [disable automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) in the future.

If you want to select a specific commit, disable this option. Note that it will also disable automatic deployments.

## Step 3. Select Server Region and Configuration

**Region**

Your application must run on a separate cloud server. Select the region where the server should be located.

**Configuration**

Select the server configuration. You can always [upgrade](https://hostman.com/docs/app-platform/managing-apps/#change-the-plan) your server later, however, downgrading will not be possible.

## Step 4. Configure Additional Settings

App Platform reads the instructions from `docker-compose.yml` and builds the application accordingly.

Here you can add the app to a private network and set up [enviroment variables](https://hostman.com/docs/app-platform/variables/), if necessary. 

Click **Show advanced settings** to configure them. 

**Private Network**

You can add the application to a private network and specify the IP address the app will use.

> [!NOTE]
> You won't be able to change the private network after the app is deployed.

Apps with a private IP address may experience a short downtime during redeployment, as existing ports need to be freed up before the new version starts.

**Variables**

If variables are already specified in `docker-compose.yml` or in the `Dockerfile`, there's no need to duplicate them.

Environment variables can be used both during the build stage and at application runtime. To use variables as build arguments, pass them to `docker-compose.yml` as follows:

```yaml
build:
  context: .
  args:
    - ARGUMENT_VAR=${example_var}
```

After that, the variable can be referenced in the `Dockerfile`:

```shell
ARG ARGUMENT_VAR=${example_var}
```

## Step 5. Enter the App Information

Specify a name and a comment for your application to be displayed in the Hostman dashboard. You can also select a project to add the app to.

These settings can also be changed later.

## Step 6. Deploy

Click **Create**. Once the process starts, you will see the deployment log on the **Deploy** tab.

The deploy log contains all the necessary information to solve possible issues. If something goes wrong, for example, due to errors in the code, the deploy log will display the notification about it specifying the cause of the problem.

When you first deploy a project, the server installation may take some time. Once the process is completed, the application status will be updated, and you will also see a message about this in the log.

All done!

You can find the application's IP address and the technical domain linked to the app in the **Dashboard** tab. To add your own domain to the app, follow [this guide](https://hostman.com/docs/app-platform/domains/).

The application runs on ports 80 and 443.

In the future, App Platform will monitor updates in the repository and, if [automatic deployment](https://hostman.com/docs/app-platform/deployments/#enable-or-disable-autodeploy) is enabled, automatically rebuild the project with new changes.

# Deploy an Image from Docker Hub

Source: https://hostman.com/docs/app-platform/docker-hub/

App Platform lets you deploy an application directly from Docker Hub without linking accounts or configuring authentication. The only requirement is that the image must be public.

This approach works well for quickly launching prebuilt solutions when you don’t need to modify the image yourself—for example, you can deploy n8n or other services distributed via Docker Hub.

## Port Handling

App Platform automatically exposes your application through a reverse proxy.

The application port is determined from:

-   Docker image metadata (for example, `EXPOSE`);
-   Environment variables, if they explicitly define a port.

If no port is specified, a default value is used.

You don’t need to configure proxying manually—the platform automatically routes traffic from external ports 80 and 443 to the container’s internal port.

During redeployments, the application may become temporarily unavailable.

## Step 1. Choose a Docker Hub Image

1.  Go to the [App Platform](https://my.hostman.com/apps) section and click **Create app**.
2.  Open the **Docker Hub** tab.
3.  Select the Docker Hub image you want to deploy.
4.  Select a tag or digest to specify the exact image version.
5.  Set up [environment variables](https://hostman.com/docs/app-platform/variables/) if needed. You can reuse existing ones or define new values.

You can update the image, tag, and environment variables later in the application settings and trigger a new deployment.

## Step 2. Choose Region and Server Configuration

Applications run on dedicated cloud servers. Select a deployment region and an appropriate server configuration. You can choose from predefined plans or define a custom configuration under the Custom tab.

You can upgrade to a more powerful plan later if needed.

## Step 3. Configure a Private Network

Create or select a private network for the application and assign the IP address it will use.

Note that the private network cannot be changed after deployment.

Apps with a private IP address may experience a short downtime during redeployment, as existing ports need to be freed up before the new version starts.

## Step 4. Enter Application Details

Optionally, specify an application name and add a description. This information will be displayed in the dashboard.

You can also select the project the application should belong to.

These settings can be updated at any time.

## Step 5. Deploy

Click **Create**. Once the process begins, you can monitor progress in the **Deploy** tab.

Deployment logs typically include all the information you need to troubleshoot issues. If something goes wrong—such as errors in your code—the logs will provide detailed messages explaining the cause.

During the initial deployment, server provisioning may take some time. Once the process is complete, the application status will update, and a confirmation message will appear in the logs.

You can find the application’s IP address and its default technical domain on the **Dashboard** tab. You can also [configure a custom domain](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain).

# Deploy Vibe-Coded Apps

Source: https://hostman.com/docs/app-platform/ai-generated-apps/

Built something with AI? Time to put it online.

This section covers how to deploy your vibe-coded apps on Hostman App Platform quickly and without unnecessary setup. Follow the guides below to get your project live, whether it’s a prototype, a side project, or something more serious.

-   [How to Deploy an App Built with Bolt](https://hostman.com/docs/app-platform/ai-generated-apps/bolt/)
-   [How to Deploy an App Built with Claude Code](https://hostman.com/docs/app-platform/ai-generated-apps/claude-code/)
-   [How to Deploy an App Built with Codex](https://hostman.com/docs/app-platform/ai-generated-apps/codex/)
-   [How to Deploy an App Built with Cursor](https://hostman.com/docs/app-platform/ai-generated-apps/cursor/)
-   [How to Deploy an App Built with Devin Desktop](https://hostman.com/docs/app-platform/ai-generated-apps/windsurf/)
-   [How to Deploy an App Built with GitHub Copilot](https://hostman.com/docs/app-platform/ai-generated-apps/github-copilot/)
-   [How to Deploy an App Built with Google AI Studio](https://hostman.com/docs/app-platform/ai-generated-apps/ai-studio/)
-   [How to Deploy an App Built with Lovable](https://hostman.com/docs/app-platform/ai-generated-apps/lovable/)

# Deploy a Bolt App with Hostman App Platform

Source: https://hostman.com/docs/app-platform/ai-generated-apps/bolt/

Built something with Bolt and ready to share it with the world? This guide walks you through going from a Bolt project to a live, publicly accessible URL—no DevOps experience required. You'll connect Bolt to GitHub, push your code to a repository, and deploy it on [Hostman App Platform](https://hostman.com/products/app-platform/). The whole process takes about 10 minutes.

Every time you make changes in Bolt after the initial setup, they'll be published automatically, without manual redeploys.

[YouTube video player](https://www.youtube.com/embed/B5LWJTjmoww?si=NlSi8wfmSz8FzjVp)

## Before You Begin

Make sure you have:

-   A project in [Bolt](https://bolt.new/). Any app you've built and want to publish.
-   A Hostman account. Sign up at [hostman.com](https://hostman.com/signup/) if you don't have one yet.

## Step 1. Create a GitHub Account

GitHub is where your project's code will live. Hostman connects to it to pull your app and build it. If you already have a GitHub account, skip to Step 2.

1.  Go to [github.com](https://github.com) and click **Sign up**.
2.  Register with your Google account, Apple ID, or an email address.

Once you're in, you'll see your [dashboard](https://github.com/dashboard).

![0902d2f9 709a 41df B496 De8fb6ff0a11.png](https://content.hostman.com/assets/1fb8456b-5bb6-4223-9231-66021cafbf3f.png?width=1999&height=1142)

_[GitHub](https://github.com/) Dashboard_

## Step 2. Connect GitHub to Your Bolt Account

Linking GitHub to Bolt means your code changes will flow to GitHub automatically—no manual uploads, no copy-pasting files.

**In Bolt:**

1.  Go to **Projects** → your project, and click the GitHub icon in the top-right corner.
2.  Click **Log in to GitHub** and sign in to your GitHub account.

![Ask Me Anything Site Bolt New 05 20 2026 10 10 Am](https://content.hostman.com/assets/bbdf0177-a176-4277-a428-fec7fa7f6aca.png?width=1920&height=869)

_Connecting to GitHub window in the [Bolt](https://bolt.new/) interface_

3.  On first connection, GitHub will ask for confirmation. Click **Authorize**.
4.  Follow any additional prompts to complete the setup.

## Step 3. Connect Your Project to GitHub

This step creates a GitHub repository for your project. From this point on, any changes you make in Bolt will be pushed to the repo automatically.

1.  Go to **Projects** → your project, and click the GitHub icon in the top-right corner.
2.  Click **Configure the GitHub App**.

![Ask Me Anything Site Bolt New 05 20 2026 10 13 Am](https://content.hostman.com/assets/96dba0f2-e4fa-4e64-9ab7-491ed5f3b29f.png?width=1920&height=869)

_Creating a GitHub repository in the [Bolt](https://bolt.new/) interface_

3.  Click **Install & Authorize**.
4.  Go to **Projects** → your project, and click the GitHub icon in the top-right corner again.
5.  Give your repository a name—for example, `bolt-app`.
6.  Click **Create repository**.

![Group 1321314412 05 20 2026 10 23 Am](https://content.hostman.com/assets/588dcc58-213b-4d66-ace4-879a22b57c45.png?width=1920&height=869)

_Creating a GitHub repository in the [Bolt](https://bolt.new/) interface_

Your repository will be created and your project files will be uploaded automatically. You can open the repo on GitHub to confirm everything is there.

## Step 4. Deploy on Hostman App Platform

Now let's get your app running in the cloud.

1.  Open the [Hostman dashboard](https://hostman.com) → **App Platform** → **Create app**.
2.  Connect your GitHub account and repository:
    

-   -   Click the GitHub icon.
    -   Sign in and authorize access.
    -   Select your repository from the list.

Keep **Built by the last executed commit** enabled. This lets Hostman automatically rebuild your app whenever you push changes to GitHub.

4.  Choose a deployment region and server configuration.
    
5.  Configure your app settings. Consult Bolt if you're unsure what to enter. For framework-specific guidance, refer to the Hostman docs: [Frontend](https://hostman.com/docs/app-platform/frontend-apps/) · [Backend](https://hostman.com/docs/app-platform/backend-apps/) · [Dockerfile](https://hostman.com/docs) · [Docker Compose](https://hostman.com/docs/app-platform/docker-compose/).
    

![Image 426](https://content.hostman.com/assets/4a885be2-1d9e-4706-9615-3845ffbc0051.png?width=526&height=762)

_Chatwindow in the [Bolt](https://bolt.new/) interface_

6.  Click **Create** and wait for the deployment to finish.
    

## You're Live!

Once deployment completes, go to **Dashboard** and look for the **Domain** field. That's your app's public URL. Share it with the world.

Want to use your own domain name? Head to **Settings** to [configure it](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain).

> [!NOTE]
> Going forward, just ask Bolt to make changes to your project.
>
> They'll be pushed to GitHub automatically, and Hostman will pick up the new commit and redeploy your app. No extra steps needed.

# Deploy an App Built with Claude Code

Source: https://hostman.com/docs/app-platform/ai-generated-apps/claude-code/

You've built something in Claude Code and now you want to put it online. This guide walks you through the full process: pushing your project to GitHub and deploying it on Hostman App Platform.

Along the way, you'll also set up MCP—a protocol that lets Claude Code interact with your GitHub account directly from the chat window. With it, you can create repositories and push code without touching git manually.

No prior experience with GitHub or deployment required. Just follow the steps in order.

## Before You Begin

You will need the following:

-   **A project built with Claude Code** that's ready to deploy.
-   **A GitHub account**. You'll create one in Step 1 if you don't have one yet.
-   **A Hostman account**. Sign up at [hostman.com](https://hostman.com/signup/) if needed.

## Step 1. Create a GitHub Account

GitHub is where your project's code will live. You'll need an account there so Hostman can access and deploy your app.

Already have one? Skip to **Step 2**.

1.  Go to [github.com](https://github.com) and click Sign up.
2.  Register with your Google account, Apple ID, or an email address.

Once you're registered and logged in, you will see your [dashboard](https://github.com/dashboard).

![0902d2f9 709a 41df B496 De8fb6ff0a11.png](https://content.hostman.com/assets/1fb8456b-5bb6-4223-9231-66021cafbf3f.png?width=1999&height=1142)

## Step 2. Check and Install the Claude Code CLI

To set up MCP, you need the command-line version of Claude Code. This is separate from the Claude desktop app or Cowork—even if those are installed, the CLI may not be.

Open your terminal (or PowerShell on Windows) and run: 

```shell
claude --version
```

If you see a version number, you're good to go. If the command isn't found, install it:

**macOS**

```shell
curl -fsSL https://claude.ai/install.sh | bash
```

**Windows**

```shell
irm https://claude.ai/install.ps1 | iex
```

On Windows, the installer may show a message like:

```shell
Native installation exists but C:\Users\Administrator\.local\bin is not in your PATH. Add it by opening: System Properties → Environment Variables → Edit User PATH → New → Add the path above. Then restart your terminal.
```

If that happens, add the directory to your `PATH`:

```shell
setx PATH "$($env:PATH);C:\Users\$env:USERNAME\.local\bin"
```

Then close the terminal, reopen it, and run `claude --version` again. If you see a version number, you're all set.

## Step 3. Create a Personal Access Token

Issuing a **Personal Access Token** will let Claude Code interact with GitHub on your behalf. The token allows Claude Code to create repositories and push code from the chat window.

1.  Open GitHub and click your profile icon in the top-right corner.
2.  Select **Settings**.
3.  In the left sidebar, scroll to the bottom and click **Developer settings**. Then go to **Personal access tokens** → **Tokens (classic)**.
4.  Click **Generate new token** → **Generate new token (classic)**. If GitHub asks for your password, enter it and continue.

![Personal Access Tokens Classic 05 20 2026 10 50 Am 06 04 2026 05 00 Pm](https://content.hostman.com/assets/fcb6aa29-1079-4149-827e-8070eb8ceb89.png?width=1898&height=858)

5.  Give the token a name in the **Note** field—something like `claude-code-access` so you know what it's for later.
6.  Set an expiration date in the **Expiration** field. If you don't want to go through this process again, pick **No expiration**.
7.  Under **Select scopes**, tick the permissions Claude Code will need:
    -   `repo`: lets it create, edit, and push to repositories
    -   `admin:org`: only add this if you're working with organisation repositories
8.  Click **Generate token**.

> [!NOTE]
> GitHub shows the token exactly once. Copy it now and keep it somewhere safe.
>
> Keep your token private. Anyone with this token can perform actions on your GitHub account. If you ever suspect it's been exposed, go to [GitHub settings](https://github.com/settings/tokens), delete it, and create a fresh one.

## Step 3. Set Up the GitHub MCP Server

This step connects GitHub to Claude Code via MCP, so you can create repositories and push code directly from the chat.

We'll use the local GitHub MCP server—no GitHub Copilot, Docker, or Node.js required. Just a binary you download once.

### macOS

Open your terminal and create a folder for the server:

```shell
dir="$HOME/.local/github-mcp-server"
mkdir -p "$dir"
```

Download and unpack the binary. The command below automatically picks the right version for your architecture (Apple Silicon or Intel):

```shell
case "$(uname -m)" in
 arm64) archive="github-mcp-server_Darwin_arm64.tar.gz" ;;
 x86_64) archive="github-mcp-server_Darwin_x86_64.tar.gz" ;;
 *) echo "Unsupported architecture: $(uname -m)" && exit 1 ;;
esac

url="https://github.com/github/github-mcp-server/releases/latest/download/$archive"
tarball="$dir/gh-mcp.tar.gz"

curl -L "$url" -o "$tarball"
tar -xzf "$tarball" -C "$dir"
rm "$tarball"
chmod +x "$dir/github-mcp-server"
```

Confirm the server runs correctly:

```shell
"$dir/github-mcp-server" --version
```

You should see a version number.

Now register the server with Claude Code. Replace `YOUR_TOKEN` with the token from the previous step:

```shell
claude mcp add github -s user \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_TOKEN \
  -- /Users/YOUR_USERNAME/.local/github-mcp-server/github-mcp-server stdio
```

### Windows

Open PowerShell and create a folder for the server:

```shell
$dir = "$env:USERPROFILE\.local\github-mcp-server"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
```

Download and unpack the binary:

```shell
$url = "https://github.com/github/github-mcp-server/releases/latest/download/github-mcp-server_Windows_x86_64.zip"
$zip = Join-Path $dir "gh-mcp.zip"

Invoke-WebRequest -Uri $url -OutFile $zip -UseBasicParsing
Expand-Archive -Path $zip -DestinationPath $dir -Force
Remove-Item $zip
```

> [!NOTE]
> The `x86_64` build works for most Windows machines. If you have an ARM processor, use `github-mcp-server_Windows_arm64.zip` instead.

Confirm the server runs correctly:

```shell
"$dir\github-mcp-server.exe" --version
```

Now register the server with Claude Code. Replace `YOUR_TOKEN` with your token:

```shell
claude mcp add github -s user `
  --env GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_TOKEN `
  -- "$dir\github-mcp-server.exe" stdio
```

### Verify the Connection

Run the following to confirm the server is connected:

```shell
claude mcp get github
```

Look for `Status: ✓ Connected` in the output.

Then restart Claude Code in your project folder and test MCP in the chat by asking: _What GitHub MCP tools do you have access to? List all of them._

![Image2](https://content.hostman.com/assets/e2b61d4d-fa4e-4d86-9407-1f6c6200c6b4.png?width=1999&height=1323)

If Claude Code returns a list of tools, the integration is working correctly. If something seems off, ask Claude Code to check the MCP configuration and explain what's wrong.

## Step 5. Push Your Project to GitHub

With MCP set up, you can create a repository and push your code without leaving Claude Code.

1.  Open your project chat and ask Claude Code to create a repository: _Create a new public repository on GitHub called `hostman-test-app`._ 
2.  Claude Code will ask for permission before taking action—confirm it. The repository will then appear in your GitHub account.
3.  Next, push your project to the repository: _Push the project from the current directory to this repository using GitHub MCP._

If your project files aren't in the root directory, specify the folder in your message.

> [!NOTE]
> Make sure to mention GitHub MCP explicitly. Without it, Claude Code may try to use your local git installation—and if git isn't set up, the push will fail.

4.  Confirm the action when prompted, then open the repository on GitHub to verify your files are there.

## Step 6. Deploy on Hostman App Platform

Now it’s time to deploy your app.

1.  Open the [Hostman dashboard](https://my.hostman.com) → **App Platform** → **Create app**.
2.  Connect your repository:
    -   Click the GitHub icon.
    -   Sign in and authorize access.
    -   Select your repository from the list.
3.  Keep **Build by last executed commit enabled**. This way, Hostman will automatically redeploy the app whenever you push new changes.
4.  Choose a deployment region and server configuration. If not sure, start small: you can always upgrade the server later.
5.  Configure additional settings. App Platform detects most of them automatically, so you can usually leave this step as is. If you're unsure what your project needs, ask Claude Code. For reference, see the Hostman docs: [Frontend](https://hostman.com/docs/app-platform/frontend-apps/) · [Backend](https://hostman.com/docs/app-platform/backend-apps/) · [Dockerfile](https://hostman.com/docs/app-platform/dockerfile/) · [Docker Compose](https://hostman.com/docs/app-platform/docker-compose/).
6.  Click **Create** and wait for the deployment to finish.

## You're Live!

Once deployment completes, go to **Dashboard** and find your app's public URL in the **Domain** field. To [use a custom domain](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain), head to **Settings**.

Once everything is wired up, shipping updates is straightforward:

1.  Make changes to your project in Claude Code.
2.  Ask Claude Code: _Commit the changes and push to GitHub using MCP._
3.  Hostman detects the new commit and redeploys automatically.

Your entire workflow runs through the chat. No manual git commands, no extra steps.

# Deploy a Codex App with Hostman App Platform

Source: https://hostman.com/docs/app-platform/ai-generated-apps/codex/

You built something in Codex. Now let's get it live.

This guide covers the full path from generated code to a public URL: pushing your project to GitHub, connecting it to [Hostman App Platform](https://hostman.com/products/app-platform/), and deploying. We'll also set up the GitHub MCP so Codex can create repos and push code on your behalf—no manual git required.

## Before You Begin

You will need: 

-   A project built in [Codex](https://openai.com/codex/)
-   A [Hostman](https://hostman.com/signup/) account

## Step 1. Create a GitHub Account

You'll need a GitHub account to host your code and connect it to the platform.

1.  Go to [github.com](https://github.com) and click **Sign up**.
2.  Register with Google, Apple, or an email address.

Once you're in, you'll land on your [dashboard](https://github.com/dashboard).

![Image4](https://content.hostman.com/assets/0902d2f9-709a-41df-b496-de8fb6ff0a11.png?width=1999&height=1142)

_[GitHub](https://github.com/) Dashboard_

## Step 2. Generate a GitHub Access Token

Codex needs a token to interact with your GitHub account—creating repos, pushing files, that sort of thing.

1.  Click your profile picture (top right) → **Settings**.
2.  Scroll down in the left sidebar → **Developer settings** → **Personal access tokens** → **Tokens (classic)**.
3.  Click **Generate new token** → **Generate new token (classic)**.

GitHub may ask for your password at this point—that's expected.

![Image2](https://content.hostman.com/assets/26fb64dc-287c-4ef0-92f7-5d0a51b6e633.png?width=1999&height=1122)

_Creating a token in the [GitHub](https://github.com/) interface_

**Fill in the token details:**

| **Field** | **Value** |
| --- | --- |
| Note | Something like `codex-access` |
| Expiration | No expiration (so you don't have to redo this) |

**Select scopes:**

-   `repo`: full repository access (create, edit, push)
-   `admin:org`: only needed if you're working with org repos

That's enough for everything in this guide. Don't select all scopes—there's no need to grant more access than necessary.

4.  Click **Generate token**.
5.  Copy the token now—you won't be able to see it again.

> [!NOTE]
> Treat this token like a password. If it's ever exposed, revoke it at [github.com/settings/tokens](https://github.com/settings/tokens) and generate a new one.

## Step 3. Connect GitHub to Codex via MCP

MCP lets Codex act on your GitHub account directly from the chat interface. Here's how to wire it up.

**In Codex:**

1.  Open **Settings** → **Plugins**.
2.  Open the **MCPs** tab and click **Add** → **Add MCP server**.
3.  Fill in the connection details:

| **Field** | **Value** |
| --- | --- |
| Name | GitHubMCP |
| Type | Streamable HTTP |
| URL | `https://api.githubcopilot.com/mcp/` |
| Bearer token env var | `GITHUB_TOKEN` |

4.  Save and fully restart Codex.
    

**Set the environment variable:**

Now expose your token to the system. Pick the option that fits:

#### macOS

Open Terminal and run:

For the current session only:

```shell
launchctl setenv GITHUB_TOKEN 'your-token-here'
```

To make it permanent across restarts:

```shell
echo 'export GITHUB_TOKEN="your-token-here"' >> ~/.zshrc && source ~/.zshrc
```

Replace `your-token-here` with the token you generated in Step 2.

#### Windows

Open PowerShell and run:

For the current session only:

```shell
set GITHUB_TOKEN=your-token-here
```

To make it permanent:

```shell
setx GITHUB_TOKEN "your-token-here"
```

Replace `your-token-here` with the token you generated in Step 2.

After running the command, restart Codex so it picks up the variable.

**Verify it's working:**

In the Codex chat, ask:

```shell
What MCP tools do you have available for GitHub? List all of them.
```

If you get a list of tools back—you're good to go.

![Image1](https://content.hostman.com/assets/1c232031-f9bf-43b0-b784-ea8efe08a910.png?width=1999&height=1152)

_Chat window in the [Codex](https://openai.com/codex/) interface_

**Something not working?** Ask Codex to check your config file:

-   macOS: `~/.codex/config.toml`
-   Windows: `C:\Users\<your-username>\.codex\config.toml`

## Step 4. Push Your Project to GitHub

With MCP connected, you can create a repo and push your code straight from the chat.

**Create the repository:**

In your Codex project chat, type: 

```shell
Create a new public GitHub repository called my-app
```

Codex will ask for permission to run the action—confirm it. You can verify the repo was created at [github.com](https://github.com).

![Image6](https://content.hostman.com/assets/89098176-109b-459b-b7f7-c59840253e52.png?width=1999&height=1143)

_Chat window in the [Codex](https://openai.com/codex/) interface_

**Push your code:**

```shell
Push the project from the current directory to that repository using the GitHub MCP.
```

> [!NOTE]
> **Heads up**: Explicitly mention the GitHub MCP—otherwise Codex may try to use local git, which can fail if git isn't installed or configured on your machine.

Confirm the action when prompted. When it's done, open the repo on GitHub and confirm your files are there.

## Step 5. Deploy on Hostman App Platform

Now let's get your app running.

1.  Go to the [Hostman dashboard](https://hostman.com) → **App Platform** → **Create app**.
2.  **Connect your repository**.

**Option A: Connect your GitHub account** _(recommended)_

Gives you access to all your repos and enables auto-deploy—your app will redeploy automatically whenever you push changes.

1.  Click the GitHub icon.
2.  Sign in and authorize access.
3.  Select your repo from the list.

**Option B: Connect via URL**

Good if you'd rather not grant full account access, or if your code is on a different Git host.

1.  Click **Connect the repository via URL**.
2.  Paste the repo URL.
3.  For private repos, provide a username and token.

> [!NOTE]
> Note: auto-deploy isn't available with this method. You'll need to trigger deploys manually after each push.

**Finish the setup**:

-   Select the commit to deploy.
-   Choose a deployment region and server configuration.
-   Configure additional settings. App Platform detects most of them automatically, so you can usually leave this step as is. If you're unsure what your project needs, ask Codex. Platform-specific docs: [Frontend](https://hostman.com/docs/app-platform/frontend-apps/) ·[Backend](https://hostman.com/docs/app-platform/backend-apps/) ·[Dockerfile](https://hostman.com/docs/app-platform/dockerfile/) ·[Docker Compose](https://hostman.com/docs/app-platform/docker-compose/)

Click **Create** and wait for the deploy to finish.

## You're Live!

Once deployment completes, go to **Dashboard** → look for the **Domain** field. That's your app's public URL.

Want a custom domain? Head to **Settings** to [configure it](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain).

Once MCP is set up, pushing updates is just a chat message away. Whenever you make changes to your project, just tell Codex to push them and Hostman will pick up the new commit and redeploy automatically.

# Deploy a Cursor Project on Hostman App Platform

Source: https://hostman.com/docs/app-platform/ai-generated-apps/cursor/

This guide walks you through taking a project built in Cursor and shipping it to a live URL using Hostman App Platform.

So, you've built (or generated) an app in Cursor, but you're not sure how to get it online. The path is straightforward: push your code to GitHub, connect that repository to Hostman, and deploy.

Along the way, we'll set up MCP, which lets Cursor talk to your GitHub account directly from the chat. That means creating repositories and pushing code without touching the command line.

This guide assumes no prior experience with GitHub or deployment—just follow the steps in order.

## Step 1. Create a GitHub Account

You'll need a GitHub account to host your project's code and connect it to Hostman.

1.  Go to [github.com](https://github.com/) and click **Sign up**.
    
2.  Sign up with Google, Apple, or an email address—whichever is easiest for you.
    

Once you're done, you'll land on your GitHub dashboard. 

![0902d2f9 709a 41df B496 De8fb6ff0a11.png](https://content.hostman.com/assets/1fb8456b-5bb6-4223-9231-66021cafbf3f.png?width=1999&height=1142)

_[GitHub](https://github.com/) Dashboard_

## Step 2. Generate an Access Token

Cursor needs an access token to act on your behalf on GitHub—creating repositories and pushing code.

In your GitHub account:

1.  Click your profile icon in the top-right corner and select **Settings**.
    
2.  Scroll down in the left sidebar to **Developer settings**, then go to **Personal access tokens** → **Tokens (classic)**.
    
3.  Click **Generate new token**, then **Generate new token (classic)**. GitHub may ask you to re-enter your password at this point—that's expected.
    

![Image2](https://content.hostman.com/assets/f42a4688-68a3-43ff-a654-b1ed470e8af6.png?width=1999&height=1122)

_Creating a token in the [GitHub](https://github.com/) interface_

4.  Under **Note**, give the token a descriptive name, like `Cursor-access`.
    
5.  Under **Expiration**, choose how long the token should last. If you'd rather not deal with this again, select **No expiration**.
    
6.  Under **Select scopes**, check the **repo** box to grant Cursor the necessary permissions.
    
7.  Click **Generate token**.
    

> [!NOTE]
> GitHub will show you the token once—copy it and store it somewhere safe. You won't be able to view it again.

Treat this token like a password. Don't commit it to your repository or share it publicly. If you think it's been exposed, revoke it at [github.com/settings/tokens](https://github.com/settings/tokens) and generate a new one.

## Step 3. Connect the GitHub MCP Server to Cursor

No manual configuration files needed here—you can set up the MCP connection right from Cursor's chat.

1.  Open the chat panel in Cursor and send a message like: _Connect the GitHub MCP server. Use this token to authenticate: `YOUR_GITHUB_TOKEN`._
    

Replace `YOUR_GITHUB_TOKEN` with the token you generated earlier.

![Image5](https://content.hostman.com/assets/d5384672-807e-42be-aa84-cad201ba9246.png?width=1999&height=1207)

_Chat window in the [Cursor](https://cursor.com/) interface_

2.  Wait for Cursor to finish setting up the connection, then restart Cursor.
    

From here on, Cursor can create repositories and push files on your behalf whenever you ask it to in chat.

## Step 4. Push Your Project to GitHub

Next, create a repository and push your project to it—all from within Cursor.

1.  In the chat, ask Cursor to create a repository: _Create a new public GitHub repository for my project._ 
    

Cursor will ask for permission to run this action—approve it.

![Scr 20260716 Oueq1](https://content.hostman.com/assets/66573211-e1c7-4f89-9c14-2fa49032c8ad.png?width=2508&height=1524)

_Chat window in the [Cursor](https://cursor.com/) interface_

Once the repository is created, you can confirm it exists by checking your repository list on GitHub.

2.  Now push your code. In the same chat, send: _Push the project in the current directory to this repository using the GitHub MCP server._ 
    

If your code lives in a subfolder rather than the project root, mention that folder explicitly.

> [!NOTE]
> Be specific about using MCP. If you don't mention it, Cursor may default to a local `git` command instead—which will fail if Git isn't installed or authenticated on your machine.

Cursor will again ask for permission before pushing—approve it, then check the repository on GitHub to confirm your files are there.

## Step 5. Deploy the Project on App Platform

With your code on GitHub, you're ready to deploy.

1.  Open the Hostman dashboard, go to **App Platform**, and click **Create app**.
    
2.  Connect your repository:
    

-   -   Click the GitHub icon.
        
    -   Sign in to your account.
        
    -   Authorize access to your repositories.
        
    -   Select the repository you want to deploy.
        

This gives Hostman access to your GitHub repositories and lets you enable auto-deploy, so your app redeploys automatically whenever you push changes.

For auto-deploy to work, keep the option **Built by the last executed commit** enabled.

4.  Select the commit to deploy (usually there's just one).
    
5.  Choose the region where your app will run and the server's configuration.
    
6.  Configure additional settings. App Platform detects most of them automatically, so you can usually leave this step as is. You can find more info on parameters in the docs for [frontend](https://hostman.com/docs/app-platform/frontend-apps/), [backend](https://hostman.com/docs/app-platform/backend-apps/), [Dockerfile](https://hostman.com/docs/app-platform/dockerfile/), and [Docker Compose](https://hostman.com/docs/app-platform/docker-compose/) apps—or ask Cursor what values to use for your setup.
    
7.  Click **Create** and wait for the deployment to finish.
    

## You’re Live!

Once the app is live, open the **Dashboard** tab. The **Domain** field shows the technical domain where your app is running. You can change this to a [custom domain](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain) anytime from **Settings**.

Going forward, shipping changes is just as simple. Make your edits to the project in Cursor and tell Cursor to commit and push these changes to the repository using the GitHub MCP server.

Hostman will pick up the new commit and redeploy automatically.

# Deploy an App Built with Devin Desktop (Windsurf)

Source: https://hostman.com/docs/app-platform/ai-generated-apps/windsurf/

Devin Desktop (formerly Windsurf) lets you build applications using built-in AI agents you can choose from directly in the chat: Cascade, its successor Devin Local, or the cloud-based Devin Cloud. This guide walks through the setup using the Devin Local agent.

Follow these steps to connect GitHub, link it to Devin Desktop, and deploy your project on Hostman App Platform—so future updates go live automatically.

## Prerequisites

Before you start, make sure you have:

-   A project in [Devin Desktop](https://devin.ai/desktop/)
-   A [Hostman](https://hostman.com/signup/) account

You will also need a GitHub account. We’ll show you how to create it in Step 1.

## Step 1. Create a GitHub Account

This is where your code will live.

1.  Go to [GitHub](https://github.com/) and click **Sign up**.
2.  Register with Google, Apple, or email.

Once registered, you'll land on the [GitHub Dashboard](https://github.com/dashboard) with your new account.

![0902d2f9 709a 41df B496 De8fb6ff0a11.png](https://content.hostman.com/assets/1fb8456b-5bb6-4223-9231-66021cafbf3f.png?width=1999&height=1142)

_[GitHub](https://github.com/) Dashboard_

## Step 2. Create a GitHub Personal Access Token

This token lets your AI agent push code to GitHub for you.

1.  In GitHub, click your account icon in the top right corner.
2.  Go to **Settings** → **Developer settings** → **Personal access tokens** → **Tokens (classic)**.

![Image1](https://content.hostman.com/assets/a04834f1-5e3e-4550-b590-ab8857bcb883.png?width=1906&height=891)

_Creating a token in the [GitHub](https://github.com/) interface_

3.  Click **Generate new token**, then select **Generate new token (classic)**.
    
    GitHub may ask for your password or a confirmation code sent to your email. This is a standard security check.
    
4.  In the **Note** field, give the token a name (anything you'll recognize later).
5.  In the **Expiration** field, set how long the token should remain valid.
6.  Select these permissions:
    -   `repo`: to work with repositories 
    -   `user`: to access profile information 
    -   `admin:org`: only if you're using organization repositories 
    -   `delete_repo`: optional, if you want to delete repositories through MCP
7.  Click **Generate token**.

> [!NOTE]
> Copy your token now—GitHub only shows it once. Save it somewhere safe.
>
> If this token leaks, anyone can act as you on GitHub. If that happens, revoke it at [github.com/settings/tokens](https://github.com/settings/tokens) and make a new one.

## Step 3. Connect GitHub to Devin Desktop

This lets your agent create repos and push code without you touching git.

1.  Click **Devin – Settings** in the bottom right corner, then go to **Advanced Settings**.
    

![Image3 06 19 2026 11 30 Am](https://content.hostman.com/assets/bd084fba-fb00-4401-9667-d171ca86d517.png?width=1916&height=1080)

_Settings in the [Devin Desktop](https://devin.ai/desktop/) interface_

2.  Go to the **Devin Local** tab and click **Open Devin MCP marketplace**.
    

![Image4 06 19 2026 11 31 Am](https://content.hostman.com/assets/57968b1b-33b6-4316-b4bf-f01660711575.png?width=1915&height=1017)

_Devin Local page in the [Devin Desktop](https://devin.ai/desktop/) interface_

3.  Click **Add custom MCP**.
    

![Image5 06 19 2026 11 32 Am](https://content.hostman.com/assets/9036c062-4ed1-41b3-b10c-dcd51f9a1ed9.png?width=1912&height=1009)

_MCP Marketplace in the [Devin Desktop](https://devin.ai/desktop/) interface_

4.  Paste this configuration:
    

```shell
{
  "mcpServers": {
    "github": {
      "serverUrl": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

5.  Replace `YOUR_TOKEN` with the token from Step 2
6.  Select **File** → **Save**.
    
7.  Close Devin Desktop completely, then relaunch it.
    

You should now see GitHub listed as **Enabled**. To double check, ask the agent in chat: _Which GitHub MCP tools are available right now?_

## Step 4. Push Your Project to GitHub

Ask the agent directly in chat: _Create a public repository called `hostman-devin-app` in my GitHub account._

The agent will ask you to confirm the action before proceeding. Once approved, the new repository appears in GitHub.

Next, push your project's code to that repository, again asking the agent: _Push the current project to this repository using GitHub MCP._

If your project isn't in the root folder, specify the correct directory in your request.

## Step 5. Deploy on Hostman

With your code in GitHub, you're ready to deploy.

1.  Open the Hostman dashboard and go to **App Platform**.
    
2.  Click **Create app**.
    
3.  Click the **GitHub** icon.
4.  Sign in to your GitHub account and confirm access.
    
5.  Select your repository from the list.
    
6.  Keep the **Build by the last executed commit** option enabled. It allows Hostman to automatically redeploy your app whenever you make changes to it.
7.  Choose a deployment region and server configuration.
    
8.  Configure the remaining application settings. These vary depending on your project type. App Platform detects most of them automatically, so you can usually leave this step as is. If you're unsure what to enter, ask the agent in Devin Desktop to walk you through the settings for your specific project.
    
9.  Click **Create** and wait for the deployment to finish.
    

## You're Live!

Hostman gives you a working domain under **Dashboard** → **Domain**. Want your own domain? [Configure it](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain) under **Settings**.

From now on, the workflow is very simple:

1.  Make changes to your project in the Devin Desktop chat.
    
2.  Ask the agent to push those changes to GitHub.
    
3.  Hostman automatically triggers a new deployment.
    

No manual git needed—just chat with your agent, and Hostman will do the rest for you.

# Deploy an App Built with GitHub Copilot

Source: https://hostman.com/docs/app-platform/ai-generated-apps/github-copilot/

GitHub Copilot is great at helping you build things fast: scaffold a UI, wire up the logic, generate a working project right in the browser or your IDE. But once the code is ready, you still need to get it online.

This guide takes you from a local Copilot project to a live, publicly accessible URL. You'll create a GitHub repository, push your code to it, connect it to Hostman App Platform, and deploy your app. By the end, you'll have a public link and a straightforward workflow for shipping updates going forward.

## Before You Begin

Make sure you have:

-   **A project built with GitHub Copilot** that's ready to deploy.
-   **A GitHub account** for hosting your code.
-   **A Hostman account** for deploying the app. Sign up at [hostman.com](https://hostman.com/signup/) if you don't have one yet.

> [!NOTE]
> This guide uses the web version of GitHub Copilot. Make sure you're logged into the same GitHub account in your browser as in Copilot—that's the account Hostman will connect to.

## Step 1. Create a Repository

Your code needs to live somewhere before Hostman can deploy it. A GitHub repository is that place.

1.  On [github.com](https://github.com), click **New** next to your repository list, or click the **\+ icon** in the top-right corner and select **New repository**.
    

![Git Hub 05 29 2026 10 28 Am 05 29 2026 11 18 Am](https://content.hostman.com/assets/561f193f-7223-41ee-ba92-390f79793767.png?width=1517&height=752)

_Creating a repository in the [GitHub](https://github.com/) interface_

2.  Enter a name in the **Repository name** field.
3.  Click **Create repository**.

![Image3 05 29 2026 11 19 Am](https://content.hostman.com/assets/09a1fd1e-c59d-47b1-90ed-da983c1151b5.png?width=1999&height=1169)

_Creating a repository in the [GitHub](https://github.com/) interface_

Once created, your repository will be available at a URL in this format: 

```shell
https://github.com/USERNAME/REPONAME.git
```

## Step 2. Push Your Project to the Repository

Now let's get your code into that repository using Copilot.

1.  Open the web version of GitHub Copilot.
2.  In the context selector, click **All repositories** and choose the repository you just created.

![Image1 05 29 2026 10 30 Am](https://content.hostman.com/assets/4789da9c-b86d-4bfe-8e17-2312100afa2a.png?width=1999&height=1138)

_Selecting a repository in the [GitHub Copilot](https://github.com/features/copilot) interface_

3.  In the chat, type: _Upload this project to this repository_.
    

Copilot will handle the upload. Once it's done, open the repository on GitHub and confirm that all your project files are there before moving on.

## Step 3. Connect Your Repository to Hostman and Deploy

With your code on GitHub, you're ready to deploy.

1.  Go to the [Hostman dashboard](https://my.hostman.com).
2.  Navigate to **App Platform** and click **Create app**.
3.  Connect your GitHub account and repository:
    

-   -   Click the GitHub icon.
    -   Authorize Hostman to access your GitHub account.
    -   Select your repository from the list.

5.  Leave **Build by last executed commit enabled**. With this on, every new commit you push to GitHub will trigger an automatic rebuild and redeploy on Hostman.
6.  Choose a deployment region. Pick the one closest to your target audience to keep latency low.
7.  Select server configuration (not available for frontend apps). If you're not sure, start small: you can always upgrade later while downgrading won't be possible.
8.  Configure your app settings. App Platform detects most of them automatically, so you can usually leave this step as is. If you're unsure what to fill in, ask Copilot to explain what's needed for your specific setup. Here's our platform-specific docs: [Frontend](https://hostman.com/docs/app-platform/frontend-apps/) · [Backend](https://hostman.com/docs/app-platform/backend-apps/) · [Dockerfile](https://hostman.com/docs/app-platform/dockerfile/) · [Docker Compose](https://hostman.com/docs/app-platform/docker-compose/).
9.  Click **Create** and wait for the build to finish.

## You're Live!

Once the deploy completes, Hostman assigns your app a public domain. Find it in **Dashboard** under the **Domain** field. You can also [connect a custom domain](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain) later from **Settings**.

Once everything is wired up, shipping an update takes just one command to Copilot:

1.  Make your changes in Copilot.
2.  Tell Copilot: _Commit the changes and push to GitHub._
3.  Hostman detects the new commit and redeploys automatically.

That's your entire workflow. No manual deploys, no extra steps.

# Deploy an App Built with Google AI Studio

Source: https://hostman.com/docs/app-platform/ai-generated-apps/ai-studio/

Google AI Studio lets you build a working app from a single text prompt—the UI, logic, and code are generated directly in your browser, no local development environment needed. 

The catch is that your app lives inside the AI Studio sandbox. To share it with the world via a public URL, you need to export the project and deploy it somewhere.

This guide takes you from a finished AI Studio app to a live deployment on Hostman App Platform:

-   export your app's code to a GitHub repository;
-   connect the repository to Hostman App Platform;
-   configure the build and publish your app;
-   set up automatic redeployments on every code change.

By the end, you'll have a public URL for your app and a workflow where pushing changes to GitHub is all it takes to trigger a new build.

## Prerequisites

Before you start, make sure you have:

-   an app built in [Google AI Studio](https://aistudio.google.com/);
-   [a Hostman account](https://hostman.com/signup/) to deploy your app.

You will also need a GitHub account which we'll cover in Step 1, if you don't have it yet.

AI Studio runs in the browser at [aistudio.google.com](https://aistudio.google.com/) and exports code via a built-in GitHub integration, which you connect through OAuth directly from the interface. 

> [!NOTE]
> Make sure you use the same GitHub account in both AI Studio and Hostman. This ensures that repositories created through AI Studio are visible when you connect your account to Hostman.

## Step 1. Create a GitHub Account

You'll need GitHub to store your app's code and connect it to Hostman.

If you already have one, sign in and skip to the next step.

1.  Go to [github.com](https://github.com/) and click **Sign up**.
2.  Register using your Google account, Apple account, or email address.

Once registered, you'll land on your GitHub dashboard.

![0902d2f9 709a 41df B496 De8fb6ff0a11.png](https://content.hostman.com/assets/1fb8456b-5bb6-4223-9231-66021cafbf3f.png?width=1999&height=1142)

_[GitHub](https://github.com/) Dashboard_

## Step 2. Connect GitHub to AI Studio

In this step, you link AI Studio to GitHub and push your app's code to a new repository.

**In AI Studio:**

1.  On the **Build** page, click the settings icon (gear) in the top-right corner.
    
2.  Go to the **GitHub** tab.
    
3.  Click **Sign in to GitHub to continue** and complete the OAuth flow. GitHub may ask you to confirm your login via email—this is expected. 
    

If your account is already connected, you'll see the **Sync to GitHub** form straight away.

![Image3](https://content.hostman.com/assets/70d770b6-e3ef-4fc0-b12e-3f15f1cb294a.png?width=1999&height=1061)

_"Sync to GitHub" option in the [Google AI Studio](https://aistudio.google.com/) interface_

4.  Fill in the repository details:
    
    -   **New repository name**: a name for your repository, no spaces.
        
    -   **New repository description**: a short description of your project.
        
    -   **Visibility**: leave it set to **Private** (the default). Private repositories work fine with Hostman when connected via your GitHub account.
        
5.  Click **Create GitHub repository**.
    
6.  In the **Sync to GitHub** window that opens, review the files to be pushed and click **Stage and commit all changes**.
    
7.  Open the repository on GitHub and confirm that all your project files are there.
    

## Step 3. Connect the Repository to Hostman and Deploy

With your code on GitHub, you're ready to deploy.

5.  Go to [hostman.com](https://hostman.com/) and sign in to your dashboard.
    
6.  Navigate to **App Platform** and click **Create app**.
    
7.  Connect your repository:

-   Click the **GitHub** icon and sign in to GitHub;
    
-   Grant Hostman access to your GitHub account;
    
-   Select your repository from the list.
    

9.  Keep the **Build by last executed commit** option enabled. This tells Hostman to automatically rebuild and redeploy your app on every new commit.
10.  Select a deployment region closest to your target audience to minimise latency.
     
11.  Select server configuration (not available for frontend apps). If you're not sure, start small: you can always upgrade later while downgrading won't be possible.
12.  Configure your app settings. App Platform detects most of them automatically, so you can usually leave this step as is. If you're unsure what to fill in, ask AI Studio to explain what's needed for your specific setup. Here's our platform-specific docs: [Frontend](https://hostman.com/docs/app-platform/frontend-apps/) · [Backend](https://hostman.com/docs/app-platform/backend-apps/) · [Dockerfile](https://hostman.com/docs/app-platform/dockerfile/) · [Docker Compose](https://hostman.com/docs/app-platform/docker-compose/).
13.  Click **Create** and wait for the build to complete.
     

## You’re Live!

Once deployed, Hostman assigns your app a public domain. Find it in **Dashboard** → **Domain**. You can share it right away or [configure](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain) your custom domain in **Settings**.

From now on, keeping your app up to date is straightforward:

1.  Make changes to your app in AI Studio.
    
2.  Open the GitHub panel and push the changes using the commit button.
    
3.  Hostman detects the new commit and automatically triggers a redeployment.
    

Your app stays live and up to date with every push.

# Deploy a Lovable App with Hostman App Platform

Source: https://hostman.com/docs/app-platform/ai-generated-apps/lovable/

You've built something in Lovable. Now let's put it on the internet. 

The good news: deploying from Lovable is one of the smoothest experiences in vibe-coding. Connect your GitHub account to the project, and your code is already in place and ready to ship. No terminal, no configuration files, no guesswork.

This guide covers taking your Lovable project from the editor to a live, publicly accessible URL via [Hostman App Platform](https://hostman.com/products/app-platform/). The whole process takes around 10 minutes. And once it's set up, every change you make in Lovable goes live automatically—no manual redeploys, ever.

## Before You Begin

You'll need two things:

-   **A project in [Lovable](https://lovable.dev/)**. Something you've built and want to share—a landing page, a tool, a web app, anything.
-   **A Hostman account**. Create one at [hostman.com](https://hostman.com/signup/) if you haven't already. It only takes a minute.

## Step 1. Create a GitHub Account

Hostman doesn't pull your code directly from Lovable, it pulls from GitHub. Think of GitHub as the middleman that holds your project's files and lets Hostman know when something has changed. You'll need an account there before anything else.

Already have one? Skip to Step 2.

1.  Go to [github.com](https://github.com) and click **Sign up**.
2.  Register with your Google account, Apple ID, or an email address.

Once you're in, you'll land on your [dashboard](https://github.com/dashboard).

![0902d2f9 709a 41df B496 De8fb6ff0a11.png](https://content.hostman.com/assets/1fb8456b-5bb6-4223-9231-66021cafbf3f.png?width=1999&height=1142)

_[GitHub](https://github.com/) Dashboard_

## Step 2. Connect Your Project to GitHub

This is the step that makes everything else easy. When you link your Lovable project to GitHub, it creates a repository for your code and keeps it in sync automatically. 

Every edit you make in Lovable gets pushed to GitHub without you having to do anything.

**In Lovable:**

1.  Open your project and click the **plus icon** in the chat window.

![Lovable Git Hub](https://content.hostman.com/assets/e3599eee-f6b2-4e4a-982e-373dfd2d93ad.png?width=954&height=133)

2.  Select **GitHub**.

![Your Digital Home Lovable 2026 08 10 15 57](https://content.hostman.com/assets/f4bb0431-c15d-4e4c-aea1-ee29cc7a35ad.png?width=1020&height=533)

_Menu in the [Lovable](https://lovable.dev/) chat interface_

3.  Click **Add connection**.

4.  Click **Add account**.

![Git Lovable 2026 08 10 15 59](https://content.hostman.com/assets/db1fced1-789a-4cd6-83e9-db54feef80ba.png?width=1095&height=581)

_Connecting GitHub in the [Lovable](https://lovable.dev/) interface_

5.  A new window will open. Click **Authorize**.
6.  Click **Install and Authorize**.
7.  Enter your GitHub account password if prompted.

That's it. 

Back in Lovable, you'll see your GitHub account listed as connected, along with the name of the repository Lovable has created for your project.

Your code is already there. Go ahead and open the repo on GitHub if you want to confirm.

![Git Lovable 2026 08 10 16 18](https://content.hostman.com/assets/c532c15b-9110-48e3-84bc-1a3dcefb407d.png?width=1101&height=510)

_GitHub repository info in the [Lovable](https://lovable.dev/) interface_

> [!NOTE]
> You don't need to name the repo or configure anything. Lovable handles all of that for you.

With your project on GitHub, you're ready to deploy.

## Step 3. Deploy on Hostman App Platform

Let's get your app running in the cloud.

1.  Open the [Hostman dashboard](https://my.hostman.com) → **App platform** → **Create app**.

3.  Connect your GitHub account and repository:
    

-   -   Click the **GitHub** icon.
    -   Sign in and authorize access.
    -   Select your repository from the list.

Keep **Built by the last executed commit** enabled. This is what allows Hostman to automatically redeploy your app every time Lovable pushes a new change to GitHub.

4.  Choose a deployment region.
5.  Select server configuration (not available for frontend apps). If you're not sure, start small: you can always upgrade later while downgrading won't be possible.
6.  Configure your app settings. What you need to fill in here depends on your project type. In most cases, App Platform detects these parameters automatically, but you can adjust them if needed.  When in doubt, ask Lovable. It knows your app's stack.

![Lovable 05 26 2026 01 23 Pm](https://content.hostman.com/assets/d18997b0-e521-4296-949d-27758d47f01e.png?width=882&height=613)

_Chat the [Lovable](https://lovable.dev/) interface_

For framework-specific guidance, refer to the Hostman docs: [Frontend](https://hostman.com/docs/app-platform/frontend-apps/) · [Backend](https://hostman.com/docs/app-platform/backend-apps/) · [Dockerfile](https://hostman.com/docs/app-platform/dockerfile/) · [Docker Compose](https://hostman.com/docs/app-platform/docker-compose/).

6.  Click **Create** and wait for the deployment to finish.
    

## You're Live!

When deployment completes, head to **Dashboard** and find the **Domain** field on the right. That's your app's public URL. Copy it, share it, send it to anyone you want.

Want to use a custom domain instead? Go to **Settings** to set it up.

From here on, your workflow is as simple as it gets: make changes in Lovable, and they'll flow to GitHub automatically. Hostman sees the new commit and redeploys your app in the background. You don't have to touch a thing.

# Manage Deployments

Source: https://hostman.com/docs/app-platform/deployments/

Every time you push a change, App Platform can build and deploy your app automatically. You can also trigger, cancel, or reconfigure deployments manually.

## Enable or Disable Autodeploy

To turn on autodeploy when you create an app, leave the **Build by the last executed commit** option enabled. App Platform then monitors your repository and redeploys the app whenever a new commit appears.

To enable or disable autodeploy for an existing app:

1.  Go to **App Platform** and select your app.
2.  Open the **Settings** tab and click **Edit** next to **Deploy** **Settings**.
3.  Enable or disable **Build by the last executed commit**.
4.  Save your changes.

## Deploy with New Parameters

Changes to the build settings apply to the next deployment.

1.  Go to **App Platform** and select your app.
2.  Open the **Settings** tab and click **Edit** next to **Deploy** **Settings**.
3.  Update the parameters you need.
4.  Select a commit and save your changes.
5.  Confirm the deployment.

## Roll Back to a Previous Commit

To deploy an earlier version of your app, select one of its previous commits and run the deployment. You can also select the current commit to deploy it again.

1.  Go to **App Platform** and select your app.
2.  Open the **Deploy** tab.
3.  Select the commit you want to deploy.
4.  Click the play icon (Rollback to commit).

## Cancel a Deployment

To cancel a deployment that is in progress:

1.  Go to **App Platform** and select your app.
2.  Open the **Deploy** tab and click the pause button.

# Manage Apps

Source: https://hostman.com/docs/app-platform/managing-apps/

Restart, stop, resize, and delete your app from the dashboard. To control how your app is built and deployed, see [Manage Deployments](https://hostman.com/docs/app-platform/deployments/).

## Restart an App

If your app misbehaves, try restarting the container it runs in.

> [!NOTE]
> This option is not available for frontend apps.

1.  Go to **App Platform** and select your app.
2.  Click on the **Restart** (Restart the application container) button in the top right corner.

## Stop and Start an App

To temporarily pause your app and make it unavailable, stop its container. You can start it again at any time with the same button.

1.  Go to **App Platform** and select your app.
2.  To stop the app, click on the **Pause** button and confirm.
3.  To resume an app, click on the **Resume** button.

## Change the Plan

If an application requires more resources, you can upgrade the server it is running on. Downgrading isn't supported, because reducing the disk size risks serious damage to the file system.

> [!NOTE]
> This option is not available for frontend apps.

To upgrade the plan:

1.  Go to **App Platform** and select your app.
2.  Open the **Settings** tab and click **Select configuration**.
3.  Select the new plan and click **Save and Reload**.

## Configure the Network

> [!NOTE]
> Network settings are not available for frontend apps.

You select the private network when you create the app and can't change it afterwards.

To view the app's private network:

1.  Go to **App Platform** and select your app.
2.  Open the **Network** tab.

To add firewall rules for the app:

1.  Go to **App Platform** and select your app.
2.  Open the **Network** tab.
3.  Click **Configure** in the **Firewall** section.
4.  Select an existing firewall or create a new one.

## Delete an App

To delete an app:

1.  Go to **App Platform**.
2.  Click the three dots next to the app and click **Delete**.
3.  Confirm the action.

# Clone Apps

Source: https://hostman.com/docs/app-platform/cloning/

Cloning lets you quickly create a copy of an existing app. The new app inherits its type, connected repository, and deployment settings, including environment variables. Before cloning, you can choose a different branch, region, or configuration for the new app. Once cloned, apps run independently of each other. 

The cost of the new app may differ from the original, as it's calculated based on current pricing at the time of cloning.

> [!NOTE]
> Cloning an app does not copy its [stands](https://hostman.com/docs/app-platform/stands/).

Before cloning, make sure your balance has enough funds to cover the new app. If funds are insufficient, you'll see a payment notification when you start the cloning process.

To clone an app:

1.  Go to the **App Platform** section and click on the app you want to clone.
    
2.  Click the **Clone** icon in the top menu.
    

![App Cloning](https://content.hostman.com/assets/ad2a6232-b4f4-44a5-92ae-50d174c33c75.png?width=1584&height=905)

3.  Review the new app's settings and adjust them if needed.
    
4.  Enter a name for the app and select the project to add it to.
    
5.  Click **Create App**.
    

App Platform will automatically create the new app and start its deployment. This process may take a few minutes. The original app keeps running without interruption.

Once deployment is complete, the cloned app will be available at a new technical domain. You can find it on the **App Platform** main page or in the app's **Dashboard** tab.

# Manage Domains

Source: https://hostman.com/docs/app-platform/domains/

Every app in App Platform gets a free technical domain, and you can add your own custom domains. App Platform automatically issues a free Let's Encrypt SSL certificate for each domain.

## Technical Domain

When you create an app, App Platform assigns a free technical domain to it and issues a Let's Encrypt SSL certificate.

-   **Frontend apps**: the app becomes available on this domain as soon as the first deploy completes, so you can test it right away.
-   **Backend apps**: use the technical domain for testing and in production, for direct requests to the app.

## Add a Custom Domain

> [!NOTE]
> Adding a domain triggers a redeployment of your app. 

You can add any number of domains to a single app. App Platform automatically issues a free Let's Encrypt SSL certificate for each custom domain and renews it one week before it expires. To use your own certificate instead, see Configure a Custom SSL Certificate.

Before you start, check where the domain's DNS is managed. To manage it in Hostman, point the domain to the Hostman nameservers:

```shell
ns1.hostman.com
ns2.hostman.com
```

To add a domain to your app:

1.  Go to **App Platform** and select your app.
2.  Open the **Settings** tab.
3.  In the **Domains** section, click **Edit**.
4.  Choose how to add the domain:
    -   If the domain uses Hostman nameservers, select it from the list.
    -   If the domain's DNS is managed by another provider:
        1.  Select **External domain** and enter the domain name.
        2.  At your DNS provider, add the A record shown in the dialog.
        3.  Wait for the DNS changes to propagate. This can take some time.
5.  Click **Save**.

## Remove a Domain

Removing a domain triggers a redeploy of your app.

To remove a domain:

1.  Go to **App Platform** and select your app.
2.  Open the **Settings** tab.
3.  In the **Domains** section, click **Edit**.
4.  Click the X icon next to the domain.

# Configure a Custom SSL Certificate

Source: https://hostman.com/docs/app-platform/ssl/

An SSL certificate enables secure HTTPS connections. When you add a custom domain to your app, App Platform automatically issues a free Let's Encrypt certificate for it and renews it before it expires.

If you've purchased a certificate separately, you can use it instead of Let's Encrypt.

## Limitations

-   You can replace the certificate only for a custom domain assigned to your app. App Platform manages the certificate for the technical domain.
-   You can't change the certificate while the app is unpaid or blocked.
-   Installation fails if the certificate has expired, was issued for a different domain, or doesn't match the private key.
-   A wildcard certificate for `*.example.com` doesn't cover `example.com` itself. To use it for the root domain, make sure `example.com` is also listed in the certificate.
-   Any certificate change triggers a redeploy. The new certificate takes effect only after the deployment completes.

## Install a Custom Certificate

Before you start, [add your custom domain](https://hostman.com/docs/app-platform/domains/) to the app.

1.  Go to **App Platform** and select your app.
2.  Open the **Settings** tab.
3.  Next to **SSL certificates**, click **Configure**.
4.  Select a domain from the drop-down list.
5.  On the **Custom** tab:
    -   Paste the certificate text into the **Certificate** field, or click **Upload from file** and select a `.crt` file. You can provide the full certificate chain.
    -   Paste the key text into the **Private key** field, or upload a `.key` file.
6.  Click **Reinstall**.
7.  Confirm the action.

Wait for the deployment to finish. Once it completes, the domain will use the new certificate.

> [!NOTE]
> App Platform doesn't renew custom certificates. Upload a new certificate before the current one expires.

## Remove a Custom Certificate

1.  Go to **App Platform** and select your app.
2.  Open the **Settings** tab.
3.  Next to **SSL certificates**, click **Configure**.
4.  Select a domain from the drop-down list.
5.  Open the **Custom** tab and click **Delete**.
6.  Confirm the action.

A domain can't be left without a certificate, so App Platform automatically issues a Let's Encrypt certificate for it again and renews it as usual. This triggers a redeploy, and the Let's Encrypt certificate takes effect once the deploy completes.

# Web Server Configuration

Source: https://hostman.com/docs/app-platform/web-server-configuration/

App Platform automatically configures the web server when you create an application. If needed, you can adjust how requests and responses are handled: set up redirects, configure HTTP headers, or enable data compression.

The available settings depend on the type of application. For frontend applications, you can also configure how missing paths are handled. For backend and Docker applications, you can limit the request body size and set a timeout for response headers.

Web server settings apply to all domains linked to the application.

## Changing Web Server Settings

To change the web server settings:

1.  Go to the **App Platform** section and select the application you want to configure.
    
2.  Open the **Settings** tab.
    
3.  Next to **Web Server Settings**, click **Configure**.
    
4.  Specify the parameters you need.
    
5.  Click **Save**.
    

Saving these settings triggers a new deployment of the application.

## General Settings

Redirects, HTTP headers, and compression are available for all application types.

### Redirects

Redirects let you forward requests from one path or domain to another. You can add up to 10 redirects per application.

To configure a redirect, specify:

-   **Type**: `path` or `host`
-   **Source**: The original path or domain
-   **Destination**: The target path or domain
-   **Code**: The response code. Available values are:
    -   **301**: Permanent redirect
    -   **302**: Temporary redirect
    -   **307**: Temporary redirect that preserves the request method and body
    -   **308**: Permanent redirect that preserves the request method and body

#### Path-based redirects

For a path-based redirect, select the `path` type. Both **Source** and **Destination** must start with `/`, for example, `/old` and `/new`.

Keep the following restrictions in mind:

-   The source and target paths must be different
-   Paths can't include query parameters (after `?`) or fragments (after `#`)
-   Query parameters from the original request are preserved after the redirect

For example, redirecting `/old` to `/new` means a request to `/old?source=mail` will be redirected to `/new?source=mail`.

#### Host-based redirects

For a host-based redirect, select the `host` type. You can only choose source and target domains from those already linked to the application.

### Headers

You can add, replace, or remove HTTP headers in the web server's responses. You can configure up to 10 rules per application.

For each header, choose a type:

-   `set`: Assign a new value to a header or replace its existing value
-   `add`: Add another value for the header
-   `delete`: Remove the header from the response

For the `set` and `add` types, specify both the header name and value. For `delete`, specify only the name.

For a single header name, you can't:

-   Create more than one set rule
-   Combine different types, for example, `set` with `add`, or `add` with `delete`

Multiple `add` rules for the same header are allowed.

### Compression

Compression reduces the amount of data the web server sends to the client, which can speed up how quickly your application loads.

To enable compression, choose one or more algorithms:

-   `gzip`
-   `zstd`

## Frontend App Settings

Frontend applications have an additional setting called **SPA Fallback**.

### SPA Fallback

SPA Fallback determines what file the application returns when a request is made to a path that doesn't exist.

If this option is enabled, the web server returns the `/index.html` file.

If it's disabled and the build includes a `/404.html` file, the web server returns that file instead. If no such file exists, the browser shows a blank page with a 404 response code.

## Backend and Docker App Settings

For backend applications, as well as applications deployed using a Dockerfile, Docker Compose, or a Docker Hub image, you can additionally configure the maximum request body size and a timeout for response headers.

### Maximum Request Body Size

This setting limits the size of incoming HTTP request bodies. For example, you can use it to cap the size of uploaded files.

Enter a number greater than `0`. The value is measured in KB, so you don't need to specify a unit.

The maximum allowed request body size is 1,048,576 KB (1 GB).

If a request body exceeds this limit, the web server rejects the request before it reaches the application.

### Response Header Timeout

This setting defines how long the web server waits for response headers from the application.

Enter a number greater than `0`. The value is measured in milliseconds, so you don't need to specify a unit. For example, to set a one-second timeout, enter `1000`.

The maximum allowed timeout is 120,000 milliseconds (120 seconds).

# Health Checks

Source: https://hostman.com/docs/app-platform/healthcheck-path/

A health check path allows the platform to periodically verify that your application is running and functioning correctly.

By default, if no health check is enabled, the platform performs only a basic check after deployment: it makes sure that the application’s container has started successfully. In this case, the actual application health is not evaluated—the app may be responding incorrectly or not responding at all, yet the deployment will still be marked as successful.

To prevent this, you can configure a health check path. Your application must expose an endpoint that does not depend on external systems (such as a database or third-party services) and accurately reflects the application’s internal state.

You can specify this endpoint during configuration: for example, `/health`, `/status`, or `/ping`.

By default, during deployment the system checks only the root URL (`/`). It sends a request to the main page, and if the response status is not in the `2xx` range, the deployment is considered unsuccessful.

## How Health Checks Work

Health check requests are always made from `localhost`.

The only requirement is that the endpoint returns a `2xx` status code. The response body does not matter; only the status code does.

### During Redeployment

If a health check path is configured, the system sends up to three consecutive `GET` requests to the new application instance.

-   If at least one request returns a `2xx` status code, the deploy is considered successful, and the new version becomes active.
-   If all three attempts fail (any status code other than `2xx`), the deploy is marked as unsuccessful, and the previous version remains active.

Health checks continue until one of the following conditions is met:

-   a single successful response,
-   three consecutive failed responses, with the last one occurring 40 seconds after startup,
-   or 180 seconds elapse; if none of the above occur within this time, the deploy is considered unsuccessful.

If the check fails, a health-check failure message will appear in the deployment logs.

### After Startup

Once a deployment succeeds, the system continues to check the application's health with one request every 30 seconds.

If three consecutive checks fail, the application is automatically restarted. This event will appear in the application logs.

## Configuring a Health Check Path

You can configure a health check path when creating a new application or later for an existing one.

### When Creating an Application

In the **Advanced settings** section, enter the desired path in the **Health Check Path** field.

For example, if your application provides a `/health` endpoint accessible at `https://domain/health`, set:

```shell
/health
```

### For an Existing Application

1.  Open the application in the Hostman dashboard.
2.  Go to the **Settings** tab.
3.  In the **Deploy settings** section, click **Edit**.
4.  Enter the health check path.
5.  Click **Save Data**.

A new deployment will automatically be triggered with the updated setting.

## Docker and Docker Compose

### Dockerfile Deployments

If your application is deployed via a Dockerfile, you can configure the health check path in the dashboard.

In this case, the dashboard setting takes precedence, and any `HEALTHCHECK` instruction in the Dockerfile is ignored.

Example:

```shell
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
  CMD curl -f http://localhost/health || exit 1
```

For more details, see the [official Docker documentation](https://docs.docker.com/reference/dockerfile/#healthcheck).

### Docker Compose Deployments

For Docker Compose deployments, configuring the health check path in the dashboard **is not supported**.

If your services use a Dockerfile, you may configure `HEALTHCHECK` directly inside it—it will behave as described above.

# Environment Variables

Source: https://hostman.com/docs/app-platform/variables/

In App Platform, you can use variables to store and pass configuration values such as passwords, file paths, tokens, and other environment parameters.

## Limits

-   Up to 1000 variables per application
-   Variable key (name): up to 255 characters
-   Variable value: up to 10240 characters

## Types of Variables

There are two types of variables: local and global.

**Local variables:**

-   Are scoped to a single application
-   Are deleted together with the application
-   Are configured when creating or editing an application

**Global variables:**

-   Are stored separately from applications
-   Can be reused across multiple applications
-   Are managed centrally in **App Platform** → **Variables**

## Local Variables

Local variables can be defined when creating an application or by editing the settings of an existing one.

### Creating a Local Variable

#### When creating an Application

You can add local variables during application creation.

1.  Go to **App Platform** and start creating an application.
2.  In the **Advanced settings** step, click **Add** in the **Variables** section.
3.  Enter the variable name and value. To add more variables, click **Add More**.

![894ee047 D580 424b 9def 6eb6cdc0f60c](https://content.hostman.com/assets/8259c495-cdc8-4f3a-be02-b412d4138d86.png?width=660&height=577)

4.  Enable **Save as global** if you want this variable to be available to other applications.

You can also upload variables from a file. To do this, click **Upload from File** and select a `.env` file. Only files named `.env` are supported. Variables must be defined in the following format:

```shell
APP_NAME=MyApp
APP_ENV=production
DB_HOST=localhost
DB_PORT=3306
```

#### In an Existing Application

1.  Go to **App Platform** and select the application.
2.  Open the **Settings** tab and click **Edit** next to **Deploy Settings**.

![371959d8 47a6 42c0 9b1b 9a00a93f0999](https://content.hostman.com/assets/d9623937-59ff-4e80-a018-395c2589adfb.png?width=1548&height=804)

3.  In the **Variables** section, click **Add**.

![Ceffe6bc 5e4f 4783 9d96 Ee873103841b](https://content.hostman.com/assets/773448ce-8876-4b76-9943-c441bff3a5b7.png?width=1536&height=1340)

4.  Enter the variable name and value. To add more variables, click **Add More**.
5.  Enable **Save as global** if you want this variable to be available to other applications.

![894ee047 D580 424b 9def 6eb6cdc0f60c](https://content.hostman.com/assets/8259c495-cdc8-4f3a-be02-b412d4138d86.png?width=660&height=577)

### Editing a Local Variable

1.  Go to **App Platform** and select the application.
2.  Open the **Settings** tab and click **Edit** next to **Deploy Settings**.

![371959d8 47a6 42c0 9b1b 9a00a93f0999](https://content.hostman.com/assets/d9623937-59ff-4e80-a018-395c2589adfb.png?width=1548&height=804)

3.  In the **Variables** section, click the pencil icon next to the variable you want to edit.
4.  Make the changes and save.

### Deleting a Local Variable

1.  Go to **App Platform** and select the application.
2.  Open the **Settings** tab and click **Edit** next to **Deploy Settings**.
3.  Click the ✕ icon next to the variable you want to delete.

## Global Variables

Global variables are managed centrally and are available under **App Platform** → **Variables**.

### Creating a Global Variable

1.  Go to **App Platform** → **Variables** and click **Add**.
2.  Enter the variable name and value. To add more variables, click **Add More**.
3.  You can also upload variables from a file by clicking **Upload from file**. Only `.env` files are supported. Variables must be defined in the following format:

```shell
APP_NAME=MyApp
APP_ENV=production
DB_HOST=localhost
DB_PORT=3306
```

Once added, global variables can be selected when creating a new application or editing an existing one. 

### Editing a Global Variable

1.  Go to **App Platform** → **Variables**.
2.  Click the three-dot menu next to the variable and select **Edit**.

![F807e719 Cf3f 46c3 9fb1 32cff263cc9a](https://content.hostman.com/assets/376bd84e-a84a-4d2e-a1c3-da16d81d6c45.png?width=1537&height=794)

3.  Make the changes and click **Save**.

### Deleting a Global Variable

1.  Go to **App Platform** → **Variables**.
2.  Click the three-dot menu next to the variable and select **Delete**.
3.  Confirm the deletion.

If the variable is used by any applications, a list of those applications will be shown. To keep the variable in those applications as a local variable, enable **Keep variable as local**.

![54414636 4d09 45ee 99d0 6aa99fce58a5](https://content.hostman.com/assets/a98f789e-1c02-45b8-81dd-2f7eceb5534a.png?width=1552&height=840)

# Staging Environments (Stands)

Source: https://hostman.com/docs/app-platform/stands/

Staging environments (stands) are isolated staging environments that allow you to test changes without affecting the main version of your application.

A stand is deployed as an independent instance of the application with its own build and is accessible via a separate technical domain.

Staging environments are available for frontend, backend, and Docker-based applications.

The maximum number of environments per application is 10.

For backend and Docker applications, stands are provided free of charge and are deployed on the same virtual machine as the main application. A stand uses the resources of that machine, so sufficient capacity must be available for it to run.

For frontend applications, [requests are billed](https://hostman.com/docs/app-platform/billing/) in the same way as for the main application.

Stands are not supported for applications deployed via Docker Compose.

## Create a Staging Environment

To create a staging environments:

1.  Go to the **App P****latform** section and click on the application.
2.  Go to the **Stands** tab.
3.  If no stands have been created yet, you will see the branch selection step. Click on it. Otherwise, click **Add stand**.

![2f7e7dab 928f 437b Bf0a 1a5913a3ccb5](https://content.hostman.com/assets/b0de4162-7974-4df4-9251-3d48a8cdb1a3.png?width=1571&height=827)

3.  Specify:
    -   the environment name;
    -   the repository branch;
    -   the commit to build, or enable the option to use the latest commit;
    -   already existing variables or add new ones.
4.  Click **Create**.

![An Js1 Ve87 M](https://content.hostman.com/assets/1398f26e-99b6-43e4-8215-6f0b612ad986.png?width=1570&height=869)

A deployment will be triggered. A technical domain will be automatically generated for accessing the application in this staging environments.

## Manage Staging Environments

All created environments are listed in the **Stands** tab.

### View the Application URL

To copy the URL where the application is available:

1.  Go to the **App Platform** section and click on the application.
2.  In the **Stands** tab, hover over the stand and click on the view icon. 

![D1aade1d 54e6 48b7 A510 5b1c3d48a285](https://content.hostman.com/assets/b75ed47d-e6a2-47a8-aab2-59a3f3e2498e.png?width=1577&height=769)

You can also copy the URL from the **Settings** tab.

### Update Staging Settings

1.  Go to the **App Platform** section and click on the application.
2.  In the **Stands** tab, click on the environment to open the details.
3.  In the **Settings** tab, you can:
    -   enable or disable the environment;
    -   rename it;
    -   change the repository branch;
    -   change the commit;
    -   manage variables;
    -   copy the stand URL.

![Stand](https://content.hostman.com/assets/a3a541d5-232f-44b6-a717-9dec689d839b.png?width=1564&height=1067)

### View Logs

1.  Go to the **App Platform** section and click on the application.
2.  In the **Stands** tab, click on the environment to open the details.
3.  Go to the **Stand logs** tab to view:
    -   deployment logs;
    -   application logs (for backend and Docker applications);
    -   access logs (for frontend applications).

![76fc77ca 1759 42cd Ac31 1af87cc4e4ca](https://content.hostman.com/assets/169e8192-8f41-4230-ad5c-010479e419b4.png?width=1572&height=817)

### Delete a Staging Environment

To delete an environment:

1.  Go to the **App Platform** section and click on the application.
2.  In the **Stands** tab, click on the three-dot menu next to the environment and select **Delete**.
3.  Confirm deletion.

![76fc77ca 1759 42cd Ac31 1af87cc4e4ca](https://content.hostman.com/assets/99019741-09f9-4bc2-bed3-839be4cc0f0c.png?width=1572&height=817)

# Automatic Staging Environments for Pull Requests

Source: https://hostman.com/docs/app-platform/pr-staging/

App Platform can automatically create a staging environment whenever you open a pull request in GitHub. Each environment is a separate deployment of your app built from the pull request's branch, with its own technical domain. Use it to test changes before merging them into the target branch.

While the pull request is open, every new commit you push to the branch updates the environment. For general information about staging environments, see [Staging Environments](https://hostman.com/docs/app-platform/stands/).

## Requirements and Limits

-   Your repository must be connected through your GitHub account. Repositories connected by URL are not supported.
-   Each app can have up to 10 staging environments. Once you reach the limit, new pull requests won't get an environment, even if automatic deploy is enabled.
-   The setting is per app. If several apps are deployed from one repository, only those with the setting enabled get staging environments. See [Monorepos](https://hostman.com/docs/app-platform/pr-staging/#monorepos).

## Enable Automatic Staging Environments

1.  Go to **App Platform** and select your app.
2.  On the **Stands** tab, click **Automation**.
3.  Turn on **Automatic deploy on Pull Request**.
4.  (Optional) Turn on **Pass application variables automatically** to copy your app's variables into new staging environments. See [Environment Variables](https://hostman.com/docs/app-platform/pr-staging/#environment-variables) below.
5.  Click **Save**.

Open a pull request in the connected repository. App Platform creates a staging environment and starts the deployment.

## Pass Variables to Staging Environments

By default, a new staging environment doesn't inherit the variables of your main app. You can change this so they're copied automatically. The setting applies to all staging environments of the app, including those you create manually.

1.  Go to **App Platform** and select your app.
2.  On the **Stands** tab, click **Automation**.
3.  Turn on **Automatic deploy on Pull Request**.
4.  Turn on **Pass application variables automatically**.
5.  Click **Save**.

Keep in mind:

-   Variables are copied only once, when the environment is created. If you later change the variables of your main app, update the staging environment separately.
-   If you copy connection parameters for a database or an external service, the staging environment will use the same resource as your production app. To avoid changing production data during testing, set separate values in the staging environment's settings instead.

## Allow Comments in GitHub

When a staging environment is created, the Hostman Apps bot posts a comment in the pull request with the deployment status and links to the environment. To do this, the GitHub integration needs read and write access to pull requests.

New integrations have this permission by default, including those you disconnect and reconnect in the App Platform dashboard. Integrations connected earlier may need updated permissions. Without them, staging environments are still created, but no comments appear in GitHub.

If you don't see a warning in step 2 below, no action is needed.

1.  Go to **App Platform** and select your app.
2.  On the **Stands** tab, click **Automation**. If you see the **No access to GitHub comments** warning, continue with the next steps.
3.  Click **Configure access** in the warning.
4.  In GitHub, on the **Installed GitHub Apps** tab, find **Hostman Apps** and click **Review request**.
5.  Check that the requested permission is **Read and write access to Pull requests**, then click **Accept new permissions**.

![Hostman Apps Permissions 2026 10 08 16 26 2026 10 08 16 28](https://content.hostman.com/assets/30b6c977-229c-41eb-91f1-232b10e8b270.png?width=1472&height=828)

_Hostman Apps requesting updated permissions in [GitHub](https://github.com/)_

## Monorepos

If a repository contains several apps, App Platform checks which files a pull request changes and creates an environment only for apps whose source directory is affected.

For example, say your repository has `frontend` and `backend` directories, and your app is deployed from `frontend`:

-   A pull request that changes files in `frontend` creates a staging environment.
-   A pull request that changes only `backend` doesn't create one.

> [!NOTE]
> Adding changes to `frontend` after you open a `backend`\-only pull request doesn't create an environment. To get one, close the pull request without merging and reopen it, or open a new pull request that already includes changes in `frontend`.

If a pull request changes more than 300 files, GitHub can't compare the changes. In this case, App Platform creates a staging environment regardless of which directories were affected.

## Staging Environment Lifecycle

App Platform manages the environment based on what happens to the pull request in GitHub:

| **GitHub event** | **What happens** |
| --- | --- |
| Pull request opened | App Platform creates a staging environment for the source branch and starts the deployment. |
| New commits pushed to the source branch | The environment is redeployed automatically. Its URL stays the same. |
| Pull request closed without merging | The environment is deleted. The changes are not merged. |
| Pull request merged | The environment is deleted, and the changes are merged into the target branch. If your main app is deployed from that branch with autodeploy enabled, it updates automatically. |

#### What you see after creation

The environment appears on the **Stands** tab with a **PR** label and a name based on the pull request number. For example, pull request #1 creates **PR-1**. The list shows the branch, commit, commit message, and deployment status.

After a successful deployment, the app is available at the environment's technical domain. You can find it in the environment's settings in the dashboard and in the bot's comment in the pull request. The bot updates this comment with the latest commit and deployment status on each redeploy.

## Manage a Staging Environment

To open an environment's settings, go to **App Platform** → your app → **Stands** and click the environment. From there you can rename it, manage its variables, and copy its technical domain. To view logs, open the **Stand logs** tab.

For more details, see [Manage Staging Environments](https://hostman.com/docs/app-platform/stands/#manage-staging-environments).

### Deploy a Specific Commit

By default, a pull request environment is built from the latest commit and redeploys on every push. You can't change its source branch, but you can pin it to a specific commit:

1.  Go to **App Platform** and select your app.
2.  On the **Stands** tab, click the environment.
3.  Turn off **Build from latest commit**.
4.  Select a commit.
5.  Click **Save**.

The environment stops updating automatically, and the bot posts a note in the pull request saying the environment is pinned to the selected commit.

### Keep an Environment After the Pull Request Is Closed

You can turn off automatic deletion for pull request staging environments, so they stay available after the pull request is closed.

1.  Go to **App Platform** and select your app.
2.  On the **Stands** tab, click the environment.
3.  Turn off **Delete stand when Pull Request** is closed.
4.  Click **Save**.

Now closing or merging the pull request will not delete the environment. [Delete it manually](https://hostman.com/docs/app-platform/stands/#delete-a-staging-environment) when you no longer need it.

# App Platform FAQ

Source: https://hostman.com/docs/app-platform/faq/

Here you will find the answers to the most frequently asked questions about Hostman App Platform. 

## Hostman Doesn't Show the Connected Repository. What Can I Do?

This usually happens in two cases:

-   You logged in to your GitHub, GitLab, or Bitbucket account in the Hostman panel before you added the repository.
-   You have authorized only certain repositories, not all of them, and the desired repository is not selected.

To fix the problem:

1.  Click **Add Account**.
2.  Select the platform.
3.  Log in, if necessary.
4.  Select the repository and click **Save**.

Now, the Hostman panel will show your connected repositories and you can select the one you need.

## How to Delete a Connected Repository?

You can unlink any repository added to your Hostman account. 

> [!NOTE]
> When you unlink a repository, any deployments (both automatic and manual) of all applications created from this repository will be impossible.

1.  Go to the **App Platform** section and click **Create App**.
2.  Click on the drop-down list of repositories and click **Delete** for the one you need.

![Fc206742 67da 4e95 8fbf 7cab28b4ab44](https://content.hostman.com/assets/c986e010-6be1-44f6-9644-48fb75afb831?width=739&height=485)

3.  In the next window, confirm the action.

## I Have a Self-Hosted Git Repository. How Do I Connect It to the Hostman App Platform?

At the moment, Hostman only supports repositories hosted directly on GitHub, GitLab, or Bitbucket. Unfortunately, it is not possible to deploy an application from a local (self-hosted) repository using our App Platform.

## Can I Access the Application via FTP?

The application is running inside a Docker container and it is impossible to get FTP access to it. Besides, it doesn't make sense: every new deployment will delete all files. 

You should upload the app files to the project repository, then App Platform will automatically upload them at the time of deployment.

## Can I Access the Application via SSH?

For backend applications and applications deployed via Dockerfile, you can access the container with your application using the **Console** tab in the dashboard.

## How Do I Change the Node.js Version in the Container Deployment Environment? Which Version Do You Use?

Available versions are 20, 22, and 24. You can select the Node.js version when creating a new app.

## What Version of Python Are You Using? How Can I Change It?

App Platform uses Python versions 3.10, 3.11, 3.12, 3.13, and 3.14 You can select the Python version when creating a new app.

## How Do I Link My Domain to the Application?

Please use [this guide](https://hostman.com/docs/app-platform/domains/#add-a-custom-domain).

## How Can I Manage Storage (Disk) on the Application Instance?

There is no such possibility. You need to use an external storage for data, for example, S3 or any other. It is also impossible to mount anything to the application instance over the network. You can send files via API or a protocol that does not involve mounting a network file system.

# Account Management

Source: https://hostman.com/docs/account/

Here you will find guides for managing your Hostman account.

-   [How to Restore Access to the Account](https://hostman.com/docs/account/recover-access/)
-   [How to Change the Account Password](https://hostman.com/docs/account/password-change/)
-   [How to Update Your Profile](https://hostman.com/docs/account/update-info/)
-   [How to Use Authentication with Passkey](https://hostman.com/docs/account/passkey-authentication/)
-   [How to Restrict Access to the Account](https://hostman.com/docs/account/restricting-access/)
-   [How to Manage Sessions and View Authorization Logs](https://hostman.com/docs/account/manage-sessions/)
-   [How to Create API and Terraform Tokens](https://hostman.com/docs/account/api-tokens/)
-   [How to Create Additional Users and Manage Access](https://hostman.com/docs/account/iam/)
-   [How to Use Projects](https://hostman.com/docs/account/projects/)

# Access Recovery

Source: https://hostman.com/docs/account/recover-access/

You can restore access to your Hostman dashboard using these instructions.

## Password Recovery

1.  Go to the [login page](https://my.hostman.com/login/).
2.  Click on the **Forgot password?** link.
3.  Enter the account login, email, or domain name.
4.  Enter the captcha.
5.  Click **Submit**.

We will send a link to restore access to the contact email of the account.

## Changing Email

If you don’t have access to the account’s email, please contact our support team.

# Change Password

Source: https://hostman.com/docs/account/password-change/

You can change your account password at any time. To keep your data secure, we recommend changing your password at least once a year.

To change your password:

1.  Click on your account name in the bottom left corner and go to the **Account settings**.
    
2.  On the **[Security and login](https://hostman.com/my/account/security)** tab, click **Change** in the **Password** block.
    
3.  Enter your old password and then the new one. For passwords you can use a combination of 8-30 characters, consisting of Latin letters, numbers and special characters. 
    
4.  Click **Edit** to update your password.
    

> [!NOTE]
> All sessions except the current one will be terminated.

# Update Profile Info

Source: https://hostman.com/docs/account/update-info/

You can update your profile information: the primary contact email and the account owner name.

> [!NOTE]
> To make changes, you need access to the current contact email associated with the account. If you cannot access the email, please contact our support team.

To update your profile information:

1.  Click on your username in the bottom left corner and navigate to the **Account settings** section.
2.  In the **Information** tab, click **Edit** next to **Personal details**.
3.  Enter the required details and click **Save**. We will send a confirmation link to the primary contact email of your account.
4.  Click on the confirmation link, and the changes will take effect.

# Authentication with Passkey

Source: https://hostman.com/docs/account/passkey-authentication/

For a convenient and secure login to Hostman, you can set up Passkey authentication. This technology allows you to log in using biometric data encrypted with a public key instead of entering a username and password.

Biometric data examples include:

-   Fingerprint scanning
-   Facial recognition
-   PIN or password entry

The exact method depends on your specific device and software, as well as your preferences during setup.

> [!NOTE]
> Biometric data is stored only on your device and is never transmitted elsewhere. 

Note that Passkey authorization is not available for additional account users.

## Setting Up Passkey Authentication

To set up Passkey authentication:

1.  Log in to the dashboard as usual, using your username and password or via Google/GitHub.
2.  Click on your username in the bottom left corner and go to the **Account Settings** section.
3.  In the **Security and login** tab, click **Manage** in the **Authorization via Passkey** section.
4.  Click **Link device** or **Bind hardware key**. This will open your device’s Passkey setup interface, where you can choose your preferred authentication method (FaceID, TouchID, PIN entry, etc.). Available methods will vary depending on your device and software.
5.  After successful setup, you will see the message "Passkey successfully added," and your device will appear in the list of linked devices in the dashboard.

For further logins from this device, Passkey authentication will be the default method. However, you can always choose an alternative login method. 

## Logging in with Passkey

When logging in, click **Log in with Passkey** and authenticate using your chosen method, such as entering a PIN or scanning your fingerprint.

## Unlinking a Device

You can unlink any device from Passkey authentication a few clicks:

1.  Log in to the dashboard from any linked device.
2.  Click on your username in the bottom left corner and go to the **Account settings** section.
3.  In the **Authorization via Passkey** section, click **Manage**.
4.  Click the three dots next to the device you wish to unlink and select **Delete**.
5.  Confirm the removal.

# Restricting Access to the Dashboard

Source: https://hostman.com/docs/account/restricting-access/

For additional account security, you can restrict access to your Hostman dashboard, allowing authorization only from specific IP addresses or countries. 

## Allow Access from Specific Countries

1.  Click on your username in the bottom left corner and go to the **Account settings** section.
    
2.  In the **Security and login** tab, click **Settings** in the **Allow access only from specific countries** block.
    
3.  Select the countries from which access to the dashboard should be allowed.
    
4.  Save the changes.
    
5.  To apply the restriction, toggle the switch to **Enabled**.
    

If you are currently logged in from a country not on your allowed list, the system will warn you before enabling the restriction.

## Allow Access from Specific IP Addresses

1.  Click on your username in the bottom left corner and go to the **Account Settings** section.
    
2.  In the **Security and login** tab, click **Settings** in the **Allow access only from specific IP addresses** block.
    
3.  Click **Add IP address** and enter an IP address. Click anywhere next to it to add it. 
    
4.  Repeat for all IP addresses you need to add.
    
5.  Save the changes.
    
6.  To apply the restriction, toggle the switch to **Enabled**.
    

If you are currently logged in from an IP address not on your allowed list, the system will warn you before enabling the restriction.

## Modify Restrictions

To modify country or IP address restrictions, click **Settings**, make the changes, and click **Save**.

## Disable Restrictions

To disable the restriction, turn it off by toggling the switch in the **Account settings** or remove it permanently by deleting selected countries or IP addresses.

# Session Management and Authorization Logs

Source: https://hostman.com/docs/account/manage-sessions/

Hostman logs all authorizations into your account and displays them [in the account settings](https://hostman.com/my/account/security). You can view the login history and manage active sessions.

## Authorization Logs

To view the login history:

1.  Click on your username in the bottom left corner and go to the **Account settings** → **Security and login**.
    
2.  Click **Go to history** next to **Authorization history**.
    

You can check the date and time of each authorization into the dashboard, the device and IP address used for login, as well as the country and city.

## Managing Active Sessions

You can also view and, if necessary, terminate active login sessions.

1.  Click on your username in the bottom left corner and go to the **Account settings** → **Security and login**.
2.  Click **Go to sessions** in the **Active sessions** block.
    

Here you can view all active sessions and terminate individual ones or all except the current session.

When the account password is changed, all sessions except the current one will be automatically terminated.

# API Tokens

Source: https://hostman.com/docs/account/api-tokens/

To interact with the Hostman API, you will need a token to manage services without a login and password. 

## Creating a Token

1.  Go to the [API](https://my.hostman.com/api-keys) section of your Hostman dashboard and click **Create** or **Add token**.
2.  Enter a token name that will be displayed on the **API** page.
3.  Set the expiration period for the token. If the token should never expire, select **Indefinite**.
4.  (Optional) Leave the **Hide passwords and other sensitive data** option enabled so that passwords, secrets, and private keys in API responses are replaced with the `hidden-by-api-key-policy` string.
5.  Click **Generate**.
6.  Copy and save the token locally, as you won’t be able to display it again in the dashboard.

## Managing Tokens

The account owner can view all the issued tokens in the [API](https://my.hostman.com/api-keys) section of the dashboard. 

Additional users can only access tokens they themselves have issued.

### Reissuing Tokens

Only the user who created the token can reissue it.

1.  Go to the [API](https://my.hostman.com/api-keys) section.
2.  Hover over the token and click **Rotate**.
3.  Select the validity period.
4.  Click **Generate**.
5.  Copy and save the token locally, as you won’t be able to display it again in the dashboard.

After reissuing, the old token will no longer be valid.

### Renaming Tokens

Only the user who created the token can rename it.

1.  Go to the [API](https://my.hostman.com/api-keys) section.
2.  Click on the three dots next to the token and select **Edit**.
3.  Change the token name and save the changes.

### Deleting Tokens

A user can delete tokens they themselves have issued. The account owner can delete any token on the account.

1.  Go to the [API](https://my.hostman.com/api-keys) section.
2.  Click on the three dots next to the token and select **Delete**.
3.  Confirm deletion.

# Access Management

Source: https://hostman.com/docs/account/iam/

You can manage access to your Hostman account by creating additional panel users and assigning them the necessary permissions and access levels.

This allows you to distribute access among different employees or even teams working on various projects, ensuring convenience and the security of your data.

An additional user can have full access to the entire account or limited access only to specific projects or resources, depending on your settings.

For example, you can grant:

-   the accountant access to payments and documents,
-   the development team access to the specific project they are working on,
-   the network administrator access to network and IP address management, and so on.

# IAM Features

Source: https://hostman.com/docs/account/iam/iam-features/

When setting up access for additional users, there are certain nuances to consider. Below, we explain them in more detail.

## Access Combinations

Some parts of the dashboard are closely linked with specific types of services (for example, SSH keys are tied to cloud servers).

When the account owner grants access to a section that has related functionality, the user will automatically receive the same level of access to those related features.

All access combinations are listed below:

**Servers:**

-   Cloud Servers
-   SSH Keys
-   Images
-   Private Networks
-   Firewall
-   Public IPs

**Databases:**

-   Databases
-   Private Networks
-   Firewall
-   Public IPs

**Balancers:**

-   Load Balancers
-   Private Networks
-   Firewall
-   Public IPs

**Networks:**

-   Private Networks
-   Firewall
-   Public IPs

**Domains:**

-   Domains
-   Domain Administrators

> [!NOTE]
> Access to the **Finances** section is always granted for the entire account. Even if a user is limited to specific projects, the **Billing** section will show all account services.

## Available to All Users

Each additional user can:

-   Enable or disable dark mode
-   Access the API section

Any token issued by an additional user will have the same permissions as the user themselves. 

## Available to Account Owner Only

The following sections and options are always available only to the account owner:

-   Notifications
-   Users
-   Feedback
-   News
-   Referral Program
-   Project Management (creating, deleting projects, and moving services between projects)

## "Read Only" Access

It’s important to note that the "Read only" permission allows a user to see all information in a section, including passwords.

For example, a user with "Read only" access to the **Databases** and **Cloud Servers** sections won’t be able to create or delete servers or databases in the panel, but they can still retrieve access credentials and connect via standard methods (e.g., SSH).

## Creating Services Without Access to Finances

Users with "Management" access to a specific section can create new services in that section, even if they cannot access the **Finances** section or view the balance.

If the account balance is sufficient, the service will be successfully created.

## Contacting Support

When an additional user contacts support, we check their access level for the section related to the request.

**Management**: Support can perform all actions available for the service except deletion. The client must delete resources themselves.

**Read only**: Support cannot perform any actions on the service without approval from the primary account. In this case, we require additional verification of the user as the account owner or ask the primary account to submit the request.

**No access**: We do not disclose any information about the service. To proceed, we must verify the user as the primary account holder or receive the request directly from the account owner.

#### Restrictions

-   **Server transfers between accounts**: Only primary users can submit these requests.
-   **Deletion and backup restoration**: Support does not perform these actions.
-   **Adding or configuring additional users**: Only the account owner can do this.
-   **Access issues**: If an additional user has trouble accessing the account or specific sections, they must contact the account owner directly to resolve the issue.

# User Management

Source: https://hostman.com/docs/account/iam/user-management/

You can create additional account users and manage their settings.

## Creating a User

To create a new user for your account, go to **[Team and Members](https://hostman.com/my/account/users)** and click **Create**. Fill in the required fields.

#### User Information

-   **Name**: Enter the user's name, for example: _Mary Smith_ or _Development Team_. The name will be visible in both your dashboard and the user's dashboard.
-   **Email**: Provide a valid email address. The user will receive a login link at this address. Note: the email cannot be changed later. If entered incorrectly, you’ll need to create a new user.
-   **Password**: You can use the auto-generated password or enter your own. The password will be shown to the user upon their first login.
-   **Comment**: Optional. You can add additional information about the user. The comment is visible to the account owner only.
-   **Avatar**: You can optionally upload an avatar for the user. The avatar is visible to the account owner only.

Only the account owner can edit this information and manage access rights.

#### Projects

Specify which projects the user should have access to:

-   **All projects**: Grants access to all projects within the account.
-   **Select projects**: Grants access to specific projects. You can choose one or more.

#### Access Permissions

Grant access to specific sections and resources of the account. Click on **No access** next to a resource and select the appropriate access level:

-   **Management**: Full access to the section, identical to that of the account owner.
-   **Read only**: Allows the user to view the section content but not make changes.
-   **No access**: The user will see a notice that access is restricted, and the content will be hidden.

> [!NOTE]
> Granting access to certain sections automatically includes access to related sections. [More details here](https://hostman.com/docs/account/iam/iam-features/#access-combinations).

After setting all necessary permissions, click **Create**. 

The new user will appear in the dashboard, and they’ll receive an email with a link to log in to the account.

## Editing Users

You can edit users’ details and permissions in two ways:

-   In the **Team and Members** section. It displays **all** additional users of the account.
    
-   In **Projects** → select a project → **Users**. This shows users with access to that specific project.
    

To edit a user’s details or permissions, click on the user.

In the **Information** tab, you can change the name, password, or comment.

> [!NOTE]
> When you change the password, Hostman won’t send it to the user. You need to contact the user directly and provide them with the new password. 

In the **Rights and access** tab, you can modify the user’s access settings.

## Users and Projects

In the **Projects** section, you can:

-   View which users have access to a specific project
-   Add existing users to a new project
-   Add existing users to an existing project
-   Edit user information
-   Block users
-   Remove users from a project
-   Remove users from the account entirely

When creating a new project, you can immediately select which users should have access to it.

![78e6d30e 88a8 4e5c 819a B4e528c8be6b](https://content.hostman.com/assets/99935be6-3d39-4cf8-aa6c-35e8d2cf8a86.png?width=615&height=655)

On the main **Projects** page, avatars of users assigned to each project will be displayed. Hover over an avatar to see the user's name.

To adjust access settings, click on the project and go to the **Users** tab. You’ll see a list of all users who have access to this project. 

Click on a user’s row to edit their information or access rights.

You can also add more users or remove users from the project.

To grant a user access to a project:

1.  Click **Add**.
2.  Select the users you want to include.
3.  Click **Save**.

To remove a user from a project:

1.  Click **Add**.
2.  Remove the user from the list.
3.  Click **Save**.

The user will be removed **from the project**, but remain on the account.

However, the **Delete** option will remove the user from the account completely:

![App Project 2026 09 22 17 11 2026 09 22 17 11](https://content.hostman.com/assets/3179c00f-181c-418d-8d4a-338c2b2212c2.png?width=1920&height=869)

## Blocking a User

If you want to temporarily restrict a user’s access to the panel, you can block them. This can be done from either the **Team and Members** or **Projects** section.

All access settings will be preserved, and after unblocking, the user will regain access according to their existing permissions.

To block a user:

1.  Go to **Team and Members** or to a project → **Users**.
2.  Hover over the user and click the lock icon.
3.  Confirm the action.

The user will now appear in the account user list with a blocked status.

If they try to log in, they’ll see a message saying the login or password is incorrect.

You can still edit a blocked user’s information and access rights. Any changes will apply once the user is unblocked.

To unblock the user, click the lock icon again and confirm.

## Deleting a User

> [!NOTE]
> If you need to temporarily restrict access, consider [blocking the user](https://hostman.com/docs/account/iam/user-management/#blocking-a-user) instead of deleting them.

To delete a user:

1.  Go to **Team and Members** or to a project → **Users**.
2.  Hover over the user and click the three-dot menu.
3.  Select **Delete**.
4.  Confirm the action.

If the user tries to log in, they will receive a message saying the login or password is incorrect.

# Working as a User

Source: https://hostman.com/docs/account/iam/working-as-a-user/

Here’s a brief overview of how additional account users view the dashboard and its sections.

## Logging In

After you create a new user, Hostman will send a link to access the dashboard to the user email you provided.

On the first login, the system will display the username and password so the user can save their credentials.

![Firstlogin](https://content.hostman.com/assets/58ce90a2-a02f-438c-abbf-7d078eb1313a.png?width=1552&height=853)

After that, users will log in using their email and password.

## "Management" Access

Sections where the user has **Management** access will appear exactly as they do for the account owner.

![Da1ec768 A6fb 4a1f Bd77 730b38e91674](https://content.hostman.com/assets/4ad1eccd-ce40-4695-b591-d9c85a880cd0.png?width=1543&height=929)

The user will be able to perform all actions: create new services, delete existing ones, and modify settings and configurations.

## "Read Only" Access

Sections with **Read Only** access can be browsed, but the user won’t be able to make changes; all options will be disabled.

![0c17fd48 25c7 4191 B074 24b9b623d592](https://content.hostman.com/assets/fbb737ab-b19c-41a6-9264-c312314800a2.png?width=1553&height=860)

> [!NOTE]
> **Note**: Read Only access allows the user to see all information in the section, **including passwords**. For example, a user with Read Only access to Cloud Servers won’t be able to delete or create servers, but they can connect to existing servers via SSH and perform any operations.

## "No Access"

In sections where the user has **No Access** permissions, a message will appear indicating insufficient permissions.

-   **If no services exist in the section**, the user will see a standard page with the access limited notice.
    

![0a81c42c 7cf0 4a9b 81d0 Aac06611757f](https://content.hostman.com/assets/9e816cae-5de5-45de-b003-6ee30814fc88.png?width=1531&height=931)

-   **If services exist**, the page will prompt the user to contact the account owner to get access:
    

![2bf8621c E72e 4131 Adc4 985bcd645ea1](https://content.hostman.com/assets/e0d9326a-c91f-4671-b593-c3375d2cb0a8.png?width=1543&height=930)

## Access to Account Settings

In the **Account Settings** section, users—regardless of their access level—will be able to view their profile information, and view their authorization history in the **Security** section.

![928db56a 88eb 4113 Ad88 672b6f475946](https://content.hostman.com/assets/fa98adac-abc6-438c-98e5-b8f3cf9c51db.png?width=1550&height=855)

In the **Personalization** section, users can also:

-   switch the dashboard layout between standard and wide views;
-   toggle between light and dark themes;
-   select their preferred interface language.

# Projects

Source: https://hostman.com/docs/account/projects/

[Projects](https://my.hostman.com/projects) are logical sections of the dashboard that allow you to group services by purpose and function.

Projects do not affect the technical operation of your services: they do not configure how services interact or change their settings. Their purpose is to keep the dashboard organized and provide a clear overview of which resources belong together.

You can add servers, cloud services, mailboxes, and domains to projects.

## Why Use Projects

-   **Logical grouping of services**

Projects help you organize services into meaningful groups.

For example, you can add a server, a cloud database, S3 storage, and a domain related to your website into a “Website” project. This makes your infrastructure easier to understand by clearly showing which resources belong to a specific product, application, or task.

-   **Access control**

Projects simplify access management within your team.

If you host multiple applications on Hostman and each one is managed by a different team, you can group each application’s services into a separate project and [grant project access](https://hostman.com/docs/account/iam/user-management/) only to the employees responsible for that application. This helps restrict access to unrelated resources and reduces the risk of mistakes.

-   **Infrastructure visualization**

Each project includes an [infrastructure diagram](https://hostman.com/docs/account/projects/infrastructure-diagram/) that shows the relationships between the added services.

This diagram makes it easier to understand how the project is structured, which is especially helpful when working in a team or handing tasks over to others.

-   **Cost transparency**

Projects make it easier to track expenses and plan your budget.

In the [Active services](https://my.hostman.com/finances/services) section, we provide detailed cost breakdowns, including per-project expenses. This allows you to see how much each project costs, compare budgets across projects, and monitor and plan your spending effectively.

# Add Services to Projects

Source: https://hostman.com/docs/account/projects/adding-services/

You can add a service to a project at any time—either during creation or later in the settings of an existing service.

## For New Services

When creating a service, you can select a project at the final step of the setup process.

![0e2f9110 Caa5 44e5 Ad86 55f3398beca7](https://content.hostman.com/assets/d370e52e-9a9c-4645-971e-ff0bf6af8692.png?width=703&height=436)

You can also start creating a service directly from a project page. In this case, the corresponding project will be automatically preselected in the creation form.

![A3b957d5 D6d9 4d1e 9085 402e6999b20d](https://content.hostman.com/assets/e1f716ca-9dc5-4b5b-9138-1e74a4b8d5e6.png?width=1554&height=846)

## For Existing Services

The easiest way to add a service to a project is from the project page itself:

1.  Select the desired project from the left-hand menu.
    
2.  Click **Add to project** at the top of the page.
    

![Bcb278d6 B497 4f64 B9bc Ff69c07f7f48](https://content.hostman.com/assets/ce5e70ad-6d32-46d8-9c51-0be091ae4786.png?width=1559&height=839)

3.  Choose one or more services you want to add to the project.
    
4.  Save your changes.
    

![0ec508ce F3fe 4332 A0a9 E5053e9fd227](https://content.hostman.com/assets/407fe5b4-5c76-4414-af33-235f8b804a9c.png?width=1547&height=844)

Alternatively, you can change the project in the service settings. For example, for servers this option is available on the **Plan** tab.

![F4436445 Bdec 4277 92ca C2283d26ae0e](https://content.hostman.com/assets/36b60331-891b-4f96-9a5d-31ef4843de02.png?width=1577&height=869)

# Access Setup

Source: https://hostman.com/docs/account/projects/access-setup/

You can create users and grant them access to services within specific projects.

![A28314d1 48bc 4f9b 8244 92554a638e04](https://content.hostman.com/assets/11f6458e-2ce3-4dc4-8634-2420bd01b092.png?width=1569&height=846)

To provide project access to selected team members:

1.  Create [additional account users](https://my.hostman.com/account/users) if they have not been created yet.
    
2.  When creating or editing a user, select the project they should have access to.
    
3.  Choose the appropriate access level for the required services (management or read-only).
    

For detailed instructions on configuring access, see the [User Management](https://hostman.com/docs/account/iam/user-management/) article.

# Infrastracture Diagram

Source: https://hostman.com/docs/account/projects/infrastructure-diagram/

The infrastructure diagram allows you to visualize the relationships between services within a single project.

To open the diagram, go to the **Projects** section or expand the project list, select the project, and navigate to the **Infrastructure Scheme** tab.

![J Qpsbpr7 Wk](https://content.hostman.com/assets/c5e1ac78-8276-46b7-910b-83e20cb8283d.png?width=1570&height=869)

By default, the diagram displays all services added to the project. When a new service is added, it automatically appears on the diagram.

Services connected to the same private network are grouped into a shared block.

To show the relationship between services, you can connect them with an arrow. To do this, click on the service and drag from one of the blue dots. When hovering over the side of another block, the arrow will automatically “snap” to it.

You can delete an arrow, comment, or text block using the **Backspace** key: select the element and press the key on your keyboard.

By clicking the three dots next to any service, you can navigate to its page. For cloud servers, you can also access to the console.

Using the menu on the left, you can:

-   Add text blocks
-   Add comments
-   Create new cloud servers, databases, load balancers, or S3 buckets

![Infra 04 16 2026 09 54 Am 04 16 2026 10 08 Am](https://content.hostman.com/assets/479feb8f-5d3d-4f0d-9550-c33a377a443b.png?width=1747&height=869)

Using the menu below the diagram, you can:

-   Zoom in and out on the diagram
-   Lock the diagram
-   Center the diagram
-   Download the diagram as a .png file
-   Switch to fullscreen mode

![J Qpsbpr7 Wk 04 16 2026 09 57 Am](https://content.hostman.com/assets/21b44579-3adf-4e67-b0d1-b353c375dc65.png?width=1570&height=869)

# AI Services

Source: https://hostman.com/docs/ai-agents/

The AI Agents platform allows you to create virtual assistants powered by [generative AI models](https://hostman.com/docs/ai-agents/pricing/#available-models).

Agents can be used for various tasks related to text generation, for example:

-   providing consultations and answering user questions in a chat format;
-   analyzing provided data and generating reports;
-   running onboarding or training programs for new employees.

The platform also allows you to add your own data sources (knowledge bases) so agents can generate relevant responses based on your domain-specific information.

You can use AI agents in your projects:

#### Via endpoints

Each agent receives its own API endpoint, which you can integrate into your application and configure with the required parameters.

#### Via a chat widget

Any agent can be embedded into a web page or application as a chat bot.

Before deploying an agent in your project, you can test its behavior and fine-tune it to your requirements using the playground (sandbox) in the dashboard.

# Available Models

Source: https://hostman.com/docs/ai-agents/models/

This page lists all language models available for AI Agents, including supported providers and reasoning capabilities. Choose the best option for your use case based on performance, speed, and reasoning support.

## Available Models List

We provide access to the following large language models:

| **Provider** | **Model** | **Reasoning** |
| --- | --- | --- |
| OpenAI | GPT 4.1 | ❌ |
| OpenAI | GPT 4.1 Mini | ❌ |
| OpenAI | GPT 4o | ❌ |
| OpenAI | GPT 5.1 | ✅ |
| OpenAI | GPT 5.2 | ✅ |
| OpenAI | GPT 5.3 Codex | ✅ |
| OpenAI | GPT 5.4 | ✅ |
| OpenAI | GPT 5.4 Mini | ✅ |
| OpenAI | GPT 5.4 Nano | ✅ |
| OpenAI | GPT 5.5 | ✅ |
| OpenAI | GPT 5.6 Luna | ✅ |
| OpenAI | GPT 5.6 Sol | ✅ |
| OpenAI | GPT 5.6 Terra | ✅ |
| OpenAI | GPT 6 Astra | ✅ |
| OpenAI | GPT 6 Sol | ✅ |
| OpenAI | GPT 6 Luna | ✅ |
| DeepSeek | DeepSeek V4 Flash | ✅ |
| DeepSeek | DeepSeek V4.1 Flash | ✅ |
| DeepSeek | DeepSeek V4 Pro | ✅ |
| xAI | Grok Code Fast | ✅ |
| xAI | Grok 4.3 | ✅ |
| xAI | Grok 4.5 | ✅ |
| xAI | Grok 4.6 | ✅ |
| Google AI | Gemini 3.1 Pro Preview | ✅ |
| Google AI | Gemini 3.1 Flash Lite | ✅ |
| Google AI | Gemini 3.5 Flash | ✅ |
| Google AI | Gemini 3.6 Flash | ✅ |
| Google AI | Gemini 3.7 Flash | ✅ |
| Google AI | Gemini 3.8 Flash | ✅ |
| Anthropic | Claude Haiku 4.5 | ✅ |
| Anthropic | Claude Sonnet 4.6 | ✅ |
| Anthropic | Claude Sonnet 5 | ✅ |
| Anthropic | Claude Opus 4.6 | ✅ |
| Anthropic | Claude Opus 4.7 | ✅ |
| Anthropic | Claude Opus 4.8 | ✅ |
| Anthropic | Claude Opus 5 | ✅ |
| Anthropic | Claude Opus 5.5 | ✅ |
| Anthropic | Claude Fable 5 | ✅ |
| Anthropic | Claude Fable 5.1 | ✅ |
| Qwen | Qwen 3.5 Flash | ✅ |
| Qwen | Qwen 3.6 Flash | ✅ |
| Qwen | Qwen 3.5 Plus | ✅ |
| Qwen | Qwen 3.6 Plus | ✅ |
| Qwen | Qwen 3.7 Max | ✅ |
| Moonshot | Kimi K2.6 | ✅ |
| Moonshot | Kimi K2.7 Code | ✅ |
| Moonshot | Kimi K3 | ✅ |
| Z.ai | GLM 4.7 FlashX | ✅ |
| Z.ai | GLM 4.7 | ✅ |
| Z.ai | GLM 5.2 | ✅ |
| Z.ai | GLM 5.3 | ✅ |
| Z.ai | GLM 5.3 Flash | ✅ |

## Reasoning Models

If a model displays a brain icon, it supports reasoning mode.

![Create AI Agent 2026 08 12 09 25](https://content.hostman.com/assets/27826505-c6fd-4a66-a3a5-d3fc6977f6bb.png?width=1424&height=832)

In this mode, the model generates intermediate reasoning steps before producing the final answer. It asks itself clarifying questions and answers them internally. This helps produce more accurate and well-structured responses, especially for complex tasks.

Each reasoning step requires additional input and output text, which increases token usage.

If a particular model supports both reasoning and non-reasoning modes, you can enable or disable its **Thinking mode** in the **Playground**:

![Daring Finch 2026 08 12 09 22](https://content.hostman.com/assets/7693eb31-ab24-4153-85e3-9a3eacecf656.png?width=1579&height=1066)

# AI Agents

Source: https://hostman.com/docs/ai-agents/manage-agents/

-   [Create Agents](https://hostman.com/docs/ai-agents/manage-agents/create/)
-   [Write System Prompts](https://hostman.com/docs/ai-agents/manage-agents/prompts/)
-   [Connect Knowledge Bases](https://hostman.com/docs/ai-agents/manage-agents/connect-knowledge-base/)
-   [Manage Skills](https://hostman.com/docs/ai-agents/manage-agents/skills/)
-   [Connect MCP Servers](https://hostman.com/docs/ai-agents/manage-agents/mcp-server/)
-   [Test Agents in the Playground](https://hostman.com/docs/ai-agents/manage-agents/playground/)
-   [Add Access Keys](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)
-   [Embed Chatbots](https://hostman.com/docs/ai-agents/manage-agents/embed-chatbots/)
-   [Chats Attachments](https://hostman.com/docs/ai-agents/manage-agents/attachments-in-chats/)
-   [External Chat](https://hostman.com/docs/ai-agents/manage-agents/external-chat/)
-   [Web Search](https://hostman.com/docs/ai-agents/manage-agents/web-search/)
-   [Image Generation](https://hostman.com/docs/ai-agents/manage-agents/image-generation/)
-   [Chat History](https://hostman.com/docs/ai-agents/manage-agents/chat-history/)
-   [Suspend and Remove Agents](https://hostman.com/docs/ai-agents/manage-agents/remove-agents/)

# Create Agents

Source: https://hostman.com/docs/ai-agents/manage-agents/create/

To create a new AI agent:

1.  Go to the **AI Services** → **Agents** section and click **Create Agent** or **Add**.
    
2.  Select the AI model for the agent. You will be able to change it later.
    
3.  Set a [token usage limit](https://hostman.com/docs/ai-agents/pricing/token-usage-limit/) to help control consumption and spending. The limit can be updated at any time in the agent settings.
    
    Agents are billed at $0.10 per month, while token usage is charged on a pay-as-you-go basis. Input and output tokens are billed separately. Service charges are deducted from your account balance hourly.
    
4.  Enable [web search](https://hostman.com/docs/ai-agents/manage-agents/web-search/), if needed.
5.  Enable image generation, if needed.
6.  Provide a [prompt for the agent](https://hostman.com/docs/ai-agents/manage-agents/prompts/). The prompt explains what the agent should do.
    

The dashboard provides several example prompts. You can review them to understand the recommended format or use them as a starting point and adjust them to your needs.

You can also [write your own prompt](https://hostman.com/docs/ai-agents/manage-agents/prompts/#prompt-guidelines) from scratch. Make sure to clearly describe what the agent should be, what tasks it must perform, and which data sources it should use.

5.  Connect an existing [knowledge base](https://hostman.com/docs/ai-agents/manage-knowledge-bases/) or [create a new one](https://hostman.com/docs/ai-agents/manage-knowledge-bases/create/) and select the [search mode](https://hostman.com/docs/ai-agents/manage-knowledge-bases/search-mode/). You can also configure the knowledge base later [in the agent settings](https://hostman.com/docs/ai-agents/manage-agents/connect-knowledge-base/).
    

Knowledge bases allow agents to generate more complete and accurate responses based on the data you provide. Examples of knowledge bases include product documentation, pricing information, or product catalogs.

6.  Connect an [MCP server](https://hostman.com/docs/ai-agents/manage-agents/mcp-server/). You can also do it later in the agent settings.
7.  Fill in the agent information: a convenient name and a comment.
    
8.  Review all selected parameters, check the service cost, and click **Create**.
    

Deployment will take a few minutes. After that, you can start working with the agent.

# Write System Prompts

Source: https://hostman.com/docs/ai-agents/manage-agents/prompts/

A prompt is a text input that determines how the model generates a response. There are two types of prompts:

-   **User prompt**: the request text from the end user.
-   **System prompt**: a text instruction that defines the agent’s behavior, including its goal, role, communication style, and limitations.

The system prompt, or instruction, affects the context in which the agent interprets requests. It is sent with every request to the model when using both the built-in widget and the API. A well-designed prompt improves the accuracy and relevance of responses.

System prompts allow you to adapt an agent for specific scenarios. For example:

-   a domain expert;
-   a specialized assistant;
-   a character with a specific communication style.

Before deploying the agent in a project, you can test it in the playground and refine the instruction if necessary.

## How to Add a System Prompt

The method for adding a system prompt depends on how the agent is used.

### OpenAI-compatible API

When using the OpenAI-compatible API, the system prompt is provided with each request as a message [with the system role](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#system).

### Widget and Native API

For the widget and the native API, the system prompt is configured in the dashboard. You can add an instruction:

-   [When creating the agent](https://hostman.com/docs/ai-agents/manage-agents/create/), by selecting one of the predefined examples or entering your own instruction;

![Be9029c2 80ca 4847 9753 4fd4c8d7dc4f](https://content.hostman.com/assets/892bd03b-0554-4b90-91ee-9211f4816f54.png?width=757&height=406)

-   Later in the **Playground** section, in the settings of an existing agent.

![Ambitious Aquila 2026 08 19 12 29](https://content.hostman.com/assets/3aeb4c11-6c5e-4c47-b9d4-80b1e0a50ae0.png?width=1575&height=885)

## Prompt Guidelines

To create the most effective instruction, include the following key elements:

-   who the agent is (for example, a travel agent or a support specialist);
-   its goals (answering questions, validating provided data, recommending services);
-   what data it should rely on (specific resources or knowledge bases);
-   its limitations (which topics it can discuss and which languages it can use).

### 1\. Agent Identity

Define the agent’s identity by specifying its name, tasks, and area of expertise.

**Good example:**

Your name is Hosti. You are a virtual assistant that helps users find answers in the Hostman documentation and provides expert recommendations based on it.

**Bad example:**

You are a virtual assistant on the Hostman website.

### 2\. Agent Goal

Define the goals as follows:

-   specify the agent’s primary objective;
-   list its key responsibilities and scope;
-   describe its priorities, type of assistance, and limitations.

**Good example:**

Your main task is to help users understand and use Hostman services. You must provide accurate, clear, and complete answers based on the Hostman documentation.

**Bad example:**

Answer questions about Hostman services.

### 3\. Agent Expertise

The agent’s expertise defines the areas and topics where it can provide accurate and relevant responses.

Use clear wording and:

-   describe the agent’s specific capabilities;
-   specify which data and knowledge bases it should rely on;
-   teach the agent to provide examples when explaining complex topics, using verified sources and avoiding fabricated examples;
-   instruct the agent to provide step-by-step instructions, formatting them with tables or code blocks when appropriate.

**Good example:**

You are a specialist in Hostman services and troubleshooting. Your primary focus is cloud databases, cloud servers, and Kubernetes.

Use the Hostman documentation as the primary source of truth and Hostman guides as a secondary source. Your knowledge should be based first on documentation and second on guide data.

Never invent information.

When answering technical questions, provide step-by-step instructions and use examples from the Hostman documentation or guides. Use tables when they help present information clearly.

**Bad example:**

You know everything about the Hostman platform based on its documentation. Do not invent answers. Add examples when helpful.

### 4\. Topics and Communication Style

Define the scope of topics and the communication style:

-   specify what the agent can talk about and which topics are restricted;
-   indicate the primary language and supported languages;
-   define the required tone and style of communication.

**Good example:**

Provide answers only based on Hostman documentation and guides. Do not discuss legal issues or handle complaints; in such cases, direct the user to support.

You understand and communicate in English, German, French, Spanish, Italian, Dutch, and Brazilian Portuguese. If a user contacts you in another language, politely ask them to rephrase the request in one of the supported languages.

Communicate politely and in a friendly manner.

**Bad example:**

Do not answer legal questions or complaints. Communicate only in English. Be polite.

### 5\. Agent Limitations

Clearly define how the agent should behave if it cannot answer a question.

-   The agent should acknowledge when it does not know the answer.
-   The agent should ask clarifying questions if the request is unclear or incomplete.
-   The agent should direct users to documentation or support when necessary.

**Good example:**

If you do not know the answer, say: “I don’t have enough information to answer this question. I’d be happy to help with something else.”

If the request is incomplete, ask for clarification: “Please provide more details about what you would like to do.”

If you are unsure about something, clearly state it and recommend consulting the Hostman documentation or contacting support.

**Bad example:**

If you cannot answer, inform the user and provide a link to the documentation.

# Connect Knowledge Bases

Source: https://hostman.com/docs/ai-agents/manage-agents/connect-knowledge-base/

A [knowledge base](https://hostman.com/docs/ai-agents/manage-knowledge-bases/) contains the materials from which an agent retrieves relevant information when generating responses. For example, this may include your product documentation or product catalogs.

If you did not connect a knowledge base when creating the agent, or if you need to replace it with another one, you can do this in the dashboard.

1.  Go to the **AI Services** → **Agents** section and click on the agent.
2.  On the **Management** tab, click **Modify** next to the knowledge base.

![Ambitious Aquila 2026 08 19 12 30](https://content.hostman.com/assets/5f11087b-828f-4c67-875b-81f48242544e.png?width=1591&height=1223)

3.  Select the required knowledge base or click **Create new** to create a new one. 
4.  Select the [search mode](https://hostman.com/docs/ai-agents/manage-knowledge-bases/search-mode/).
5.  Save the changes. 

![Ambitious Aquila 2026 08 20 12 18](https://content.hostman.com/assets/8e3f5ef2-4d17-4794-a1c9-632a3e4ba51e.png?width=1755&height=847)

# Manage Skills

Source: https://hostman.com/docs/ai-agents/manage-agents/skills/

Skills are text instructions that an AI agent uses in specific situations, without loading the full instruction into every request.

This article covers how skills work and how to create, connect, version, and delete them.

## How Skills Work

Unlike [a system prompt](https://hostman.com/docs/ai-agents/manage-agents/prompts/), the full skill instruction isn't sent to the model with every request—only the description from the When to apply field stays in context at all times. If a request matches that description, the agent pulls in the skill's full instruction as well. This keeps token usage down, since long instructions only enter the context when they're actually needed.

Skills work across the [widget](https://hostman.com/docs/ai-agents/manage-agents/embed-chatbots/), [external chat](https://hostman.com/docs/ai-agents/manage-agents/external-chat/), and the [API](https://hostman.com/docs/ai-agents/api-usage/native-api/).

A few things to know about how skills behave:

-   One agent can have multiple skills attached, and the same skill can be reused across multiple agents.
    
-   When generating a response, an agent can draw on several skills at once if the request matches more than one of their conditions.
    
-   If a skill's instructions conflict with the system prompt, the system prompt takes priority.
    
-   When a skill is used to generate a response, a label showing this appears in the chat.
    

## Create a Skill

You can create a skill from the **AI Services** → **Skills** section, or while creating an agent.

### From the Skills Section

1.  Go to **AI Services** → **Skills**.
2.  Click **Add**.
3.  Set the [skill's parameters](https://hostman.com/docs/ai-agents/manage-agents/skills/#skill-parameters).
4.  Click **Add**.

The skill will now appear under **AI Services** → **Skills**.

![AI Agents 2026 09 01 14 10](https://content.hostman.com/assets/92787ec9-b149-4aa8-a512-a338374bcf40.png?width=1754&height=834)

### When Creating an Agent

On the **Instructions and Skills** step, select an existing skill or click **Add new**. If you're creating a new skill, set its parameters and click **Add**.

![Create AI Agent 2026 09 01 14 07](https://content.hostman.com/assets/a0d6a28e-683d-4761-9eaa-a509cb151deb.png?width=608&height=359)

## Skill Parameters

When you create a skill, you'll need to specify:

-   **Skill name**: the name shown in the dashboard.
    
-   **When to apply**: describes the situations in which the agent should use the skill. This description is sent to the agent with every request.
    
-   **Instruction**: the instruction the agent follows once a request matches the **When to apply** description.
    
-   **Agents (optional)**: a list of agents to attach the skill to right away.
    

![AI Agents 2026 09 01 14 10 2026 09 01 14 11](https://content.hostman.com/assets/c8a05018-bebf-4607-acde-93b200abe0fc.png?width=519&height=772)

## Attach a Skill to an Agent

You can attach a skill to an agent right when you [create the skill](https://hostman.com/docs/ai-agents/manage-agents/skills/#create-a-skill), by selecting the agent in the **Agents** field. But you don't have to decide this upfront—you can attach a skill to any agent at any later point, or update which agents use it, from the agent's settings.

This is also where you can detach a skill or switch an agent to a different version.

1.  Go to **AI Services** → **Agents** and click on the agent.
2.  Open the **Management** tab.
3.  In the **Resources** block, click **Modify** next to **Skills**.

![Ambitious Aquila 2026 09 01 14 17](https://content.hostman.com/assets/d5f7afac-a1f9-4084-830d-417700b8f603.png?width=1573&height=1316)

4.  Select the skill and the version you want to use.

![Ambitious Aquila 2026 09 01 14 18](https://content.hostman.com/assets/12f8b60d-770b-4390-bfa1-19ef098b0d16.png?width=1744&height=847)

## Edit Skills

Editing a skill's parameters creates a new version, so you can always roll back to an earlier one. Renaming a skill is the only change that doesn't create a new version.

1.  Go to **AI Services** → **Skills**.
2.  Click the skill you want to edit.
3.  Update its parameters in the editor.
4.  Click **Save**.
5.  Choose which agents should use the new version.
6.  Click **Save** again.

You'll see a new version appear in the **Version history** on the right.

> [!NOTE]
> A skill can have up to 50 versions. Once you hit the 50th, you won't be able to save further changes—[duplicate the skill](https://hostman.com/docs/ai-agents/manage-agents/skills/#duplicatea-skill) instead if you need to keep editing.

![AI Agents 2026 09 01 14 21](https://content.hostman.com/assets/4cdc557c-e9e1-46d0-bc8f-606f7ebcf1c6.png?width=1412&height=804)

## Manage Skill Versions

Every skill has a current version—the one suggested by default whenever you attach the skill to an agent. You can always choose a different version instead, either while [attaching the skill](https://hostman.com/docs/ai-agents/manage-agents/skills/#attach-a-skill-to-an-agent) or afterward, in the agent's settings.

To set a different version as current:

1.  Go to **AI Services** → **Skills**.
2.  Click the skill you want to edit.
3.  Click the version you want in the **Version history** block.
4.  Click **Make current**.
5.  Click **Save**.

## Duplicate a Skill

Duplicating a skill creates a new one containing only the version currently selected in the editor. Version history isn't carried over, so the copy's version count starts fresh at 1.

To create a copy:

1.  Go to **AI Services** → **Skills**.
2.  Click on the the skill and select the version you want to copy.
3.  Return to the skills list, click the three dots next to the skill, and select **Duplicate**.

The copy is created instantly and appears in the list.

![AI Agents 2026 09 01 14 33](https://content.hostman.com/assets/9da1eb19-2ef7-4665-8c32-b513d5d4ee58.png?width=1570&height=828)

## Delete a Skill

To delete a skill:

1.  Go to **AI Services** → **Skills**.
2.  Click the three dots next to the skill and select **Delete**.
3.  Confirm the deletion.

# Connect MCP Servers

Source: https://hostman.com/docs/ai-agents/manage-agents/mcp-server/

MCP (Model Context Protocol) is a protocol that allows an AI agent to work not only with its own knowledge but also with external tools. For example, it enables the agent to perform web searches, work with documentation, connect to services such as Notion, manage a browser, and use the obtained results when generating a response for the user.

An MCP server acts as an intermediary between the AI agent and external services. The agent itself does not know how these services are structured or how to interact with them. However, it knows that the MCP server provides a set of available tools that it can use.

## Tool Discovery

When an AI agent connects to an MCP server, the first thing it does is request the list of available tools. In response, the server returns a description of its capabilities: function names, their purpose, the parameters they accept, and the format in which they return results.

At this stage, a contract is established between the agent and the MCP server. The agent understands which actions are available and can choose which tool to use in a particular situation.

![4](https://content.hostman.com/assets/7a9a4be7-37d5-4931-89bf-03cfb9761969.png?width=1920&height=927)

This list of tools can also be retrieved manually using a regular HTTP request. For example, the **exa search** MCP server, which provides the AI agent with access to web search, allows you to request the list of tools like this:

```shell
curl -s https://mcp.exa.ai/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }' \
| sed -n 's/^data: //p' \
| jq
```

In response, the server returns a list of tools. From this list, you can see which functions are available, what they are intended for, and which parameters they expect. For example, one tool is responsible for web search, another for company research, and a third for searching code and documentation. For each tool, the required input data is explicitly described.

It is important that the AI agent does not “guess” these parameters or invent the request format. It works strictly according to the description received from the MCP server.

## Handling User Requests

After connecting and retrieving the list of tools, the AI agent keeps in mind which tools are available and in which situations they can be used.

A user asks the AI agent a question. If the agent can answer immediately, it simply generates a response. However, if there is not enough information, the agent understands that it needs to use an external tool and sends a request to the MCP server.

You can explicitly instruct the agent to use tools. For example, when connecting Context7, you can add “Use Context7” at the end of the prompt, and the agent will use the tools of that MCP server instead of generating information.

Let’s consider interaction with an MCP server using exa search as an example. A user asks the AI agent a question. If the agent realizes that it cannot answer immediately—for example, because it lacks up-to-date information—it decides to use the search tool and sends a request to the MCP server. The MCP server performs the search function in exa search and returns a structured result to the AI agent. The agent then reads the results, selects the key information, and generates a response for the user based on this data.

![3](https://content.hostman.com/assets/b68f7111-f5a9-4cc8-a819-98c5d09af083.png?width=1920&height=927)

The MCP server does not respond directly to the user and does not make decisions. It performs specific functions and returns results. All logic, data interpretation, and response generation remain on the AI agent’s side.

## Connection Setup

There are two types of MCP servers: stdio and Streamable HTTP. They can roughly be divided into local (stdio) and remote (Streamable HTTP).

Only remote servers—Streamable HTTP—can be connected to agents.

To add a new connection:

1.  Go to **AI Services →** **MCP Servers**.
2.  Click **Create** or **Add**.
3.  Fill in the fields:
    -   **Sever name**: any name for the connection
    -   **Comment**: optional field
    -   **Server address**: the URL where the MCP server is available
    -   **Protocol**: HTTP or SSE
    -   **Authorization**: choose the authentication method:
        -   Bearer token
        -   OAuth 2.0
        -   Custom headers
        -   No authorization
4.  Click **Add Server**.

After that, the new connection will appear in the list of tools.

![AI Agents 2026 08 19 12 52](https://content.hostman.com/assets/f3d7169d-b672-4abb-bee3-9b5952e6a2ed.png?width=1750&height=827)

## Managing an Agent’s MCP Servers

To connect a server to a specific agent:

1.  Go to the **AI Services →** **Agents** section and click on the agent.
2.  In the **Management** tab, click **Modify** in the **MCP servers** row.

![Ambitious Aquila 2026 08 19 12 59](https://content.hostman.com/assets/31bb21bf-b3f2-4bd3-bdf2-a82d9cda12c9.png?width=1575&height=1231)

3.  Select an existing MCP server or click **Add new**.
4.  (Optional) Click the arrow next to the connected MCP server to select which tools the agent will use.

![Group 1 2026 08 19 13 07](https://content.hostman.com/assets/e4097b53-edcf-4ac3-b371-8ad09a927e17.png?width=1755&height=869)

To detach an MCP server from an agent, click **Delete MCP Server** in the same window.

Multiple MCP servers can be connected to a single agent. One connection can be used by multiple agents.

## Usage

After connecting an MCP server, the agent will use its functions both when working through the OpenAI-compatible API and in the widget interface.

When using the OpenAI-compatible API, connected MCP servers are applied only if the `tools` parameter is not explicitly passed in the request.

Streaming data transfer (SSE) is not currently supported for agents with connected MCP servers.

# Test an Agent in the Playground

Source: https://hostman.com/docs/ai-agents/manage-agents/playground/

The **Playground** is a testing environment where you can check how your AI agent works and fine-tune it according to your requirements.

## Test the Agent

To test an agent:

1.  Go to the **AI Services** → **Agents** section and select the agent.
2.  Open the **Playground** tab. You will see the prompt defined when the agent was created, the agent settings, and below that a chat interface for interacting with the agent.
3.  Start a conversation with the agent to evaluate the accuracy and speed of its responses, as well as the level of detail and communication style.
4.  If you need to adjust the agent’s behavior, modify its parameters.

![Ambitious Aquila 2026 08 19 12 31](https://content.hostman.com/assets/00d3d480-8b07-43fe-b264-a0a908400033.png?width=1588&height=1790)

## Modify Prompt

Refine the wording in the system prompt or add any missing requirements. Our [prompt guidelines](https://hostman.com/docs/ai-agents/manage-agents/prompts/#prompt-guidelines) can help you with this.

Click **Save changes** to apply the new prompt, then test the agent again.

## Modify Agent Settings

In the panel on the right, you can configure the agent parameters:

-   **Maximum tokens**. Specifies the maximum number of tokens the model can use in a response. Higher values allow the model to generate longer responses.
-   **Temperature**. Controls the creativity of the model. Higher values result in more creative and unpredictable (and sometimes less accurate) responses.
-   **Top P**. Defines the probability threshold for token selection. Higher values produce more diverse responses, while lower values make responses more focused and coherent.
-   **Refine search query**. If enabled, the agent reformulates your request to perform a more accurate search in the knowledge base. Disable this option to search strictly by the exact words and phrases entered.
-   **Presence penalty**. Reduces repetition by penalizing tokens that have already appeared in the text. Higher values result in fewer repetitions.
-   **Frequency penalty**. Reduces repetition based on how frequently tokens appear in the text. Higher values result in fewer repetitions.
-   **Thinking mode**. Enables the reasoning mode for the model

Click **Save changes** to apply the selected parameters to the agent, then test its performance.

# Add Access Keys

Source: https://hostman.com/docs/ai-agents/manage-agents/api-access-key/

Access keys are required to send API requests to an agent.

To add an access key:

1.  Go to the **AI Services** → **Agents** section and select the required agent.
2.  On the **Management** tab, click **Modify** in the **API access** section.

![Ambitious Aquila 2026 08 19 12 33](https://content.hostman.com/assets/9ef356ad-6dd7-41f7-8b18-6fbaf81c234d.png?width=1581&height=869)

3.  Click **Add new key**.
4.  Enter a custom name or leave the default one and click **Add**.
5.  Copy the key value and store it in a secure location. You will not be able to view it again in the dashboard.

Use the generated key in your application or website to authorize requests to the agent.

# Embed Chatbots

Source: https://hostman.com/docs/ai-agents/manage-agents/embed-chatbots/

AI agent–based chat bots can be embedded into your applications and websites so users can interact with them.

To configure the chat and get the embed code:

1.  Go to the **AI Services** → **Agents** section and select the required agent.
2.  On the **Integrations** tab, click **Configure** in the **Chat Embed** section.

![Chat Embed 2026 08 19 12 34](https://content.hostman.com/assets/723c2131-bc97-4c09-8e7a-13ab1629184f.png?width=1604&height=1199)

## Chat Interface Settings

On the **Settings** tab, you can customize the chat interface. This can be done either before embedding the chat on your website or at any time afterward.

The following options are available:

-   Agent name
-   Name subtitle
-   Welcome message
-   Accent color
-   Font
-   Icon
-   Chat widget position on the website

The selected font is not loaded together with the chat. The browser will use the font available on the user’s system if it matches the specified one. Otherwise, a similar font will be used.

## Allowed Domains

On the **Domains** tab, you can specify which websites are allowed to use the widget.

By default, the agent can be embedded on any domain. However, if you add at least one domain, the widget will only be available on the specified addresses.

## Embed Code

On the **Embed** tab, you will find the ready-to-use code that can be added to your website. Simply copy it and paste it into your HTML between the `<body></body>` tags.

# Chat Attachments

Source: https://hostman.com/docs/ai-agents/manage-agents/attachments-in-chats/

When interacting with an agent [through a chat bot](https://hostman.com/docs/ai-agents/manage-agents/embed-chatbots/) or the [external chat](https://hostman.com/docs/ai-agents/manage-agents/external-chat/), users can attach text files and images to their messages.

This option is useful in scenarios where the agent needs to analyze additional materials, such as error screenshots, photos of receipts, invoices, or other documents.

## Supported Formats

Supported file formats depend on the model you're using.

**ChatGPT, Grok:** `.c`, `.cpp`, `.cs`, `.csv`, `.doc`, `.docx`, `.gif`, `.go`, `.html`, `.iif`, `.java`, `.jpeg`, `.jpg`, `.js`, `.json`, `.kt`, `.md`, `.odt`, `.pdf`, `.php`, `.png`, `.ppt`, `.pptx`, `.py`, `.rb`, `.rs`, `.rtf`, `.scala`, `.sql`, `.swift`, `.ts`, `.tsv`, `.txt`, `.webp`, `.xls`, `.xlsx`, `.xml`, `.yaml`, `.yml`.

**Claude:** `.c`, `.cpp`, `.cs`, `.csv`, `.doc`, `.docx`, `.gif`, `.go`, `.html`, `.java`, `.jpeg`, `.jpg`, `.js`, `.json`, `.kt`, `.md`, `.pdf`, `.php`, `.png`, `.py`, `.rb`, `.rs`, `.scala`, `.sql`, `.swift`, `.ts`, `.txt`, `.webp`, `.xls`, `.xlsx`, `.xml`, `.yaml`, `.yml`.

**Gemini:** `.c`, `.cpp`, `.cs`, `.csv`, `.doc`, `.docx`, `.gif`, `.go`, `.html`, `.java`, `.jpeg`, `.jpg`, `.js`, `.json`, `.kt`, `.md`, `.pdf`, `.php`, `.png`, `.py`, `.rb`, `.rs`, `.rtf`, `.scala`, `.sql`, `.swift`, `.ts`, `.txt`, `.webp`, `.xls`, `.xlsx`, `.xml`, `.yaml`, `.yml`.

**Qwen:** `.bmp`, `.gif`, `.heic`, `.heif`, `.jpeg`, `.jpg`, `.png`, `.tif`, `.tiff`, `.webp`.

**Moonshot**, **DeepSeek****, GLM**: Attachments are not supported.

The maximum file size is **5 MB**. Multiple files can be attached at the same time.

## Token Consumption

When processing files, the agent consumes tokens. The **approximate token usage** can be estimated using the formulas below.

Image: 

```shell
(Width / 512) × (Height / 512) × 700
```

Text:

```shell
Number of characters / 4
```

# External Chat

Source: https://hostman.com/docs/ai-agents/manage-agents/external-chat/

[Hostman.AI](https://ai.hostman.com/) external chat is an interface for interacting with AI agents outside the dashboard. It lets you work with agents in a familiar chat format and use all of their features.

When you work with an agent in the external chat, it retains all the settings you configured for it in the dashboard, including system prompts, MCP server connections, and the knowledge base.

## Accessing the External Chat

You can open the external chat in two ways:

#### Via Direct Link

You'll need to be logged in to your Hostman account.

1.  Go to [ai.hostman.com](https://ai.hostman.com/).
    
2.  Click any agent in the list.
    

#### From Your Hostman Dashboard

1.  Go to **AI Services** → **Agents** and click any existing agent.
    
2.  Click **External Chat** in the top right corner.
    

The chat will open in a new browser tab.

![Inventive Umbriel 2026 08 17 13 29](https://content.hostman.com/assets/ad76271f-3b87-4ad6-af6a-c339cf07af6e.png?width=1578&height=781)

## Working with Chats

Select the agent you want to work with. The list shows all AI agents created on your account. You can switch to a different agent at any time using the dropdown menu at the top of the interface.

![Hostman AI 2026 08 17 14 00 (2)](https://content.hostman.com/assets/773805f5-edb5-49da-8c47-542a1edb6c48.png?width=1920&height=869)

To start a new conversation, click **New Chat**. 

![Hostman AI 2026 08 17 14 00](https://content.hostman.com/assets/e2ee253f-b95a-4f04-a7f1-baddfc225e56.png?width=1920&height=869)

On the left, you'll see a list of all chats created with a given agent. You can switch between them to continue a previous conversation or revisit earlier messages.

Click the three dots next to your account name in the bottom-left corner to open the menu. From there, you can go to the agent settings page, change the theme, delete all chats, or log out.

![Hostman AI 2026 08 17 14 00 (1)](https://content.hostman.com/assets/72856129-2182-4efd-893b-ff4dd1cf29fc.png?width=1920&height=869)

## Managing Access

By default, the external chat is only available to the account owner. To give access to other people, for example, specific employees or teams, you can create additional users.

Users who have been granted access to the external chat are listed under **AI Services** → **Settings** → **Manage**.

### Creating a New User

To grant access:

1.  Go to **AI Services** and open the **[Settings](https://hostman.com/my/cloud-ai/settings)** tab.
    
2.  Click **Manage**.
    
3.  Click **Add** or **Add User**.
    
4.  Enter the user's email—it will be used as their login.
    
5.  Set a password, or leave the default one. Passwords can be 8–30 characters long and may include numbers, letters, and special characters.
    
6.  (Optional) Add a comment. It will only be visible to you.
    
7.  Click **Add**.
    

The user will receive an email with a login link. On their first login, they'll be able to copy the suggested password and save it.

The user can now work with agents at [ai.hostman.com](https://ai.hostman.com/).

### Granting Access to an Existing User

If the user already exists in the dashboard, you can grant them access to the external chat:

1.  Go to **[Team and Members](https://hostman.com/my/account/users)**.
    
2.  Click the user.
    
3.  On the **Rights and access** tab, set:
    

-   **AI Agents**: _Read only_
    
-   **AI Agents External Chat**: _Management_
    

5.  Save your changes.
    

### Changing a Password

Only the account owner can change a user's password. You can do this directly from the **AI Services** section:

1.  Go to **AI Services** and open the **[Settings](https://hostman.com/my/cloud-ai/settings)** tab.
    
2.  Click **Manage**.
    
3.  Click the three dots next to the user and select **Edit**.
    
4.  Set a new password and save your changes.
    
5.  Share the new password with the user—Hostman won't send it automatically.
    

You can also change a password under **[Teams and Members](https://hostman.com/my/account/users)**.

### Revoking Access

To revoke a user's access to the external chat:

1.  Go to **[Teams and Members](https://hostman.com/my/account/users)**.
    
2.  Click the user.
    
3.  On the **Rights and access** tab, set **AI Agents External Chat** to _No Access_.
    
4.  Save your changes.
    

### Deleting a User

> [!NOTE]
> This action removes the user from the entire account, not just from AI Agents. If you want to keep their access to other sections of the panel but restrict access to agents, change their permissions instead.

To permanently delete a user:

1.  Go to **AI Services** and open the **[Settings](https://hostman.com/my/cloud-ai/settings)** tab.
    
2.  Click **Manage**.
    
3.  Click the three dots next to the user and select **Delete**.
    
4.  Confirm the action.

# Web Search

Source: https://hostman.com/docs/ai-agents/manage-agents/web-search/

You can [enable web search](https://hostman.com/docs/ai-agents/manage-agents/web-search/#configuring-web-search) so your agent can look up information online when it needs to.

This option costs $5.42 per 1,000 requests ($0.00542 per request).

## Why Use Web Search

Web search lets your agent reach out to the internet while processing a request, so it can pull in up-to-date information about current events, prices, and facts that may have changed. Without web search, the agent relies solely on the knowledge baked into the language model, which is only current up to its training cutoff.

Web search is especially useful for things like:

-   Recent news and events
-   Current prices, exchange rates, and market data
-   Information that changes over time, such as schedules, pricing plans, or company contact details
-   Verifying facts that may be outdated
-   Finding specific pages or sources related to a user's query

## When the Agent Uses Web Search

With web search enabled, the agent evaluates each incoming request and decides whether it needs to look anything up online:

-   If the model's existing knowledge is enough to answer the request, it skips the search.
-   If up-to-date information is needed for a good answer, the agent runs one or more search queries, retrieves the results, and uses them to shape its response.

> [!NOTE]
> This decision is made by the model itself—there's no way to force a search or block it for a specific request.

## Limiting the Search Scope

When [creating an agent](https://hostman.com/docs/ai-agents/manage-agents/web-search/#when-creating-an-agent), or later [in its settings](https://hostman.com/docs/ai-agents/manage-agents/web-search/#in-an-existing-agents-settings), you can restrict web search to specific domains. Instead of searching the entire internet, the agent will then only pull results from the sources you've specified.

This helps you get more accurate and relevant answers, rely only on trusted and verified sources, and filter out results from forums, aggregators, or random websites.

This is particularly useful in scenarios where the agent needs to work strictly with official data or a limited set of approved external resources.

## Configuring Web Search

You can manage web search settings both when creating an agent and afterward, from its settings.

### When Creating an Agent

On the **Pricing** step, leave the **Web search** option enabled, or turn it off if you don't need it. You can also [set up domain restrictions](https://hostman.com/docs/ai-agents/manage-agents/web-search/#limiting-the-search-scope) right away, or configure them later in the agent's settings.

![Web search settings](https://content.hostman.com/assets/2330ad68-df47-41b0-bde5-0da22da59aaf.png?width=749&height=741)

### In an Existing Agent's Settings

To configure web search for an existing agent:

1.  Go to **AI Services** → **Agents** and select the agent you want to configure.
    
2.  Open the **Management** tab.
    
3.  Click **Modify** in the **Web search** block.
    

![Web search settings](https://content.hostman.com/assets/859758a4-399c-4d41-bebd-bbeb69bd394b.png?width=1580&height=786)

4.  Turn the option on or off.
5.  If needed, [enable the domain restriction](https://hostman.com/docs/ai-agents/manage-agents/web-search/#limiting-the-search-scope) and specify the allowed domains.
    
6.  Save your changes.
    

![Web search settings](https://content.hostman.com/assets/8b6154e5-83f8-491f-a94e-277d20d3de43.png?width=1745&height=855)

# Image Generation

Source: https://hostman.com/docs/ai-agents/manage-agents/image-generation/

The image generation feature lets your agent create images from text descriptions right within the conversation.

The agent automatically detects whether a message is a request to generate an image and routes it to the [selected image model](https://hostman.com/docs/ai-agents/manage-agents/image-generation/#available-models). If the message isn't an image generation request, the agent simply replies with a regular text message.

Image generation works when interacting with the agent through the [external chat](https://hostman.com/docs/ai-agents/manage-agents/external-chat/) or an [embedded widget](https://hostman.com/docs/ai-agents/manage-agents/embed-chatbots/).

Pricing depends on the selected model and is calculated per token. Input tokens (the prompt) and output tokens (the generated image) are billed separately.

## Available Models

When you enable image generation, you can choose from the following models:

-   **Gemini 3.1 Flash Image Preview**: A fast model for generating illustrations, sketches, and drafts. Best when speed matters more than top-tier quality.
-   **Gemini 3 Pro Image Preview**: An advanced model with better detail and quality. Suited for production use cases and final illustrations.
-   **GPT Image 2**: An advanced model that delivers high detail and closely follows instructions. Ideal for final illustrations and more complex visuals.
-   **GPT Image 2.5 Flare**: A fast model that matches GPT Image 2 quality at up to half the latency. Best for high-volume generation, rapid prototyping, and interactive workflows.
-   **GPT Image 2.5 Sunburst**: A precision-focused model with higher quality than GPT Image 2 and tighter control over multi-step edits. Ideal for production-ready visuals, though generation takes longer.
-   **FLUX.2 \[pro\]**: A balanced production model weighing quality, prompt accuracy, and cost. Suited for everyday image generation and industrial-scale use.
-   **FLUX.2 \[klein\] 9B**: A compact, fast model that generates images in under a second. Best for interactive workflows, previews, and high-volume generation.
-   **FLUX.2 \[max\]**: A flagship model with top-tier quality, detail, and precise instruction-following for complex prompts. Ideal for the most demanding tasks, including intricate compositions.

You can switch models at any time [in the agent's settings](https://hostman.com/docs/ai-agents/manage-agents/image-generation/#in-an-existing-agents-settings).

## Enabling and Disabling Image Generation

You can turn image generation on or off either while creating an agent or from an existing agent's settings.

### When Creating an Agent

On the **Pricing** step, enable the **Image Generation** option and select your preferred model.

![Create AI Agent 2026 09 03 12 10 2026 09 03 12 10](https://content.hostman.com/assets/dd2e357f-765d-4e03-b52d-7475a04fe881.png?width=754&height=795)

### In an Existing Agent's Settings

1.  Go to **AI Services** → **Agents** and click the agent you want to configure.
    
2.  Open the **Management** tab.
    
3.  Click **Modify** in the **Image Generation** block.
    

![Inventive Umbriel 2026 08 17 12 52](https://content.hostman.com/assets/4a8b7ea4-fdb3-44c8-83ec-e5ec65d7e043.png?width=1581&height=869)

4.  Toggle the option on or off.
    
5.  If enabling it, select an image generation model from the dropdown.
    
6.  Click **Save**.
    

![Inventive Umbriel 2026 08 17 12 52 (1)](https://content.hostman.com/assets/a93e3266-bf1d-4817-98dc-cc76e6a3dcd6.png?width=1754&height=869)

# Running Code in a Sandbox

Source: https://hostman.com/docs/ai-agents/manage-agents/sandbox/

A sandbox is a temporary, isolated environment where an AI agent can execute code. The agent runs a script, gets back the result, and uses it to answer the user or continue with the task. The environment exists only for the duration of that task and is destroyed afterward; users never interact with it directly, only with the agent that decides when and what to run.

Agents are good at understanding requests and figuring out an approach, but not at producing exact, repeatable results—a calculation done "in the model's head" can look right without actually being correct. The sandbox covers that gap: instead of estimating an answer, the agent writes a short script, runs it on the real input, and uses the returned value.

The sandbox is available when working through the [external chat](https://hostman.com/docs/ai-agents/manage-agents/external-chat/), [widget](https://hostman.com/docs/ai-agents/manage-agents/embed-chatbots/), [native API](https://hostman.com/docs/ai-agents/api-usage/native-api/), and [OpenAI-compatible API](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/).

Running code in the sandbox is free. It's enabled by default—no separate setup is needed.

## Ways to Run Code

To complete a task in the sandbox, the agent can:

-   Use a ready-made script from an attached [skill](https://hostman.com/docs/ai-agents/manage-agents/skills/)
-   Run code the user sent in a message
-   Write its own code based on the task description

Scripts attached to skills work well for repetitive tasks, like validating data against fixed rules or converting text into a specific format.

If the agent tries to perform calculations or process data without running code, add an explicit instruction to the [system prompt](https://hostman.com/docs/ai-agents/manage-agents/prompts/). This is especially useful for less capable models:

_Perform all calculations and data processing using the code execution tool. Always compute the result with code instead of estimating it._

## How a Script Runs

Each run gets its own environment with a 30-second lifespan. Files aren't preserved between runs.

The agent passes arguments to the script as JSON over standard input (`stdin`). In Python, for example, arguments are read with `json.load(sys.stdin)`.

The script's output must be written to standard output (`stdout`). In Python, use `print()`; in Node.js, use `console.log()`.

The agent receives up to 8,000 characters of `stdout` output and uses it to generate a response. On failure, it receives up to 2,000 characters of `stderr`.

Chat attachments aren't passed directly to the script. If a script needs external files, it has to fetch them itself—for example, by downloading them from a URL.

## Limits

When writing scripts, keep these runtime limits in mind: available resources, supported file types, and how much output the agent receives.

| **Parameter** | **Limit** |
| --- | --- |
| Runtimes | Python 3.13 and Node.js 24 |
| Script execution time | Up to 30 seconds |
| RAM | 256 MB |
| CPU | 1 core |
| Supported code file formats | `.py`, `.js`, `.mjs`, `.cjs` |
| Files per run | Up to 20 |
| Total file size | Up to 10 MB |
| `stdout` passed to the agent | Up to 8,000 characters |
| `stderr` passed to the agent on error | Up to 2,000 characters |

## Available Libraries

The sandbox includes the standard Python and Node.js libraries and modules, plus the following packages:

-   **Python**: `openpyxl`, `XlsxWriter`, `xlrd`, `python-docx`, `python-pptx`, `pypdf`, `pdfplumber`, `reportlab`, `Pillow`, `numpy`, `sympy`, `python-dateutil`, `pytz`, `orjson`, `tqdm`
    
-   **Node.js**: `exceljs`, `xlsx`, `csv-parse`, `csv-stringify`, `docx`, `pdf-lib`, `jszip`, `mathjs`, `dayjs`, `lodash`
    

Installing additional libraries isn't supported.

## Usage Example

In this example, you'll calculate the SHA-256 hash of a text string using a script attached to a skill. SHA-256 is a hash computed from a text's content—every character affects the result, including spaces, line breaks, and letter case.

You'll write a Python script, attach it to a skill, and connect the skill to an agent, then test the calculation on the string `hello world`.

### Prepare the Script

Create a file named `sha256_text.py` on your computer with the following content:

```py
import hashlib
import json
import sys

args = json.load(sys.stdin)
text = args["text"]
digest = hashlib.sha256(text.encode("utf-8")).hexdigest()
print(digest)
```

The script reads a JSON object containing a text field from `stdin`, computes the UTF-8 SHA-256 hash of that text, and prints the hash to `stdout`. It relies only on Python's standard library.

### Create the Skill

1.  Go to **AI Services** → **Skills** and click **Add**.
2.  Fill in the skill's fields: 
    -   **Skill name**:
        
        _Calculate SHA-256 of text_
        
    -   **When to use**:
        
        _Use this skill when the user asks to calculate the SHA-256 hash of a piece of text._
        
    -   **Instructions**:
        
        _To calculate SHA-256, use the `sha256_text.py` script.  
        __Pass the user's text in the text field. Preserve letter case, spaces, and line breaks. Don't add characters or otherwise modify the text.  
        __If it's unclear which piece of text to process, ask the user to clarify. Return the hash from the script unchanged._
        
3.  Click **Upload script**.
4.  Upload `sha256_text.py` and fill in the fields:
    -   **Description**:
        
        _Calculates the UTF-8 SHA-256 hash of the given text and returns it in hexadecimal form._
        
    -   **Arguments**: 
        
        _The script accepts a JSON object with a required text field—the string to hash. Pass the text unchanged, preserving letter case, spaces, and line breaks._
        
        _Example: `{"text": "hello"}`_
        
5.  Click **Add**.
6.  In the **Add skill** window, select the agent that will use the skill in the **Agents (optional)** field.
7.  Click **Add**.

### Test It

Open the agent's [playground](https://hostman.com/docs/ai-agents/manage-agents/playground/) and send a request:

_Calculate the SHA-256 hash of the string "hello world". Don't include the quotation marks, and don't add extra spaces or a line break._

Following the skill's instructions, the agent should run `sha256_text.py` with the arguments:

```shell
{"text": "hello world"}
```

The script computes the hash and prints it to `stdout`:

```shell
b94d27b9934d3e08a52e52d7da7dabfac484efe37a5380ee9088f7ace2efcde9
```

The agent returns this value in its response. Compare it to the hash above—for the exact string `hello world`, with no extra characters, the values should match.

# Chat History

Source: https://hostman.com/docs/ai-agents/manage-agents/chat-history/

To evaluate the quality of the agent’s responses, you can view all conversations with it on the **Chat history** tab.

Conversations are saved when interacting with the agent [through the chat widget](https://hostman.com/docs/ai-agents/manage-agents/embed-chatbots/) on your website or when testing the agent [in the Playground](https://hostman.com/docs/ai-agents/manage-agents/playground/).

Messages are not stored when using the API.

The following filters are available for working with chat history:

-   By reactions
-   By average response time
-   By period

By clicking the download button, you can export the chat history in `.csv` format. You can select the required time period before downloading.

Only the last 2,000 messages are included in the export.

The history includes the following data: Conversation ID, Agent ID, Message ID, Message creation time, Message author, Message text, Liked response, Response time (in seconds).

# Suspend and Remove Agents

Source: https://hostman.com/docs/ai-agents/manage-agents/remove-agents/

You can at any time:

-   temporarily suspend an agent;
-   permanently delete an agent.

## Suspending an Agent

You can temporarily suspend an agent, for example, to adjust its configuration or interface and then start it again.

After an agent is suspended:

-   the chat widget on your website will stop being displayed;
-   API requests to the agent will return a 400 error.

> [!NOTE]
> When an agent is suspended, the service is billed as usual. The monthly billing date will not change.

To suspend an agent:

1.  Go to the **AI Services** → **Agents** section.
2.  Hover over the required agent and click the pause icon.
3.  Confirm suspending the agent.

![AI Agents 2026 08 19 12 35](https://content.hostman.com/assets/b49dca38-84e1-42a5-a536-60d4ba2aff24.png?width=1592&height=837)

Alternatively, open the agent and click the pause icon in the top-right corner.

![Ambitious Aquila 2026 08 19 12 35](https://content.hostman.com/assets/06384acd-a7c1-4867-b44e-1d20849033ff.png?width=1585&height=749)

## Resuming an Agent

To start the agent again after it has been suspended:

1.  Go to the **AI Services** → **Agents** section.
2.  Hover over the required agent and click the start icon.

![AI Agents 2026 08 19 12 36](https://content.hostman.com/assets/524d816f-abd2-4628-baae-9501b0bcdf12.png?width=1588&height=827)

Alternatively, open the agent and click the start icon in the top-right corner.

![Ambitious Aquila 2026 08 19 12 37](https://content.hostman.com/assets/02770207-fb66-43c8-9af1-877066f12621.png?width=1585&height=752)

## Deleting an Agent

If the agent is no longer needed, you can permanently delete it. This action cannot be undone.

> [!NOTE]
> Knowledge bases connected to the agent will not be deleted. If you no longer need them, you can remove them manually on the **Knowledge Bases** tab. 

To delete an agent:

1.  Go to the **AI Services** → **Agents** section.
2.  Hover over the required agent, click the three-dot menu on the right, and select **Delete**.
3.  Confirm the action.

![AI Agents 2026 08 19 12 39](https://content.hostman.com/assets/a8100659-9235-4cea-a5b9-41c85814d89d.png?width=1580&height=832)

Alternatively, open the agent and click the delete icon in the top-right corner.

![Ambitious Aquila 2026 08 19 12 39](https://content.hostman.com/assets/25915c1c-8f2a-4e95-824b-9a9798d36976.png?width=1589&height=749)

# Knowledge Bases

Source: https://hostman.com/docs/ai-agents/manage-knowledge-bases/

A knowledge base is a private repository of unstructured files used for Retrieval-Augmented Generation (RAG). In other words, when a knowledge base is connected, the agent does not only generate responses based on the AI model’s training data—it also searches the knowledge base for information specifically relevant to your services and offerings.

Examples of knowledge bases include product documentation, pricing information, or product catalogs.

Knowledge bases are stored in an OpenSearch cloud database, which will appear in the **Databases** section of your dashboard when you create a new knowledge base.

Local files serve as data sources. You can upload up to 100 files per batch, with a maximum size of 50 MB each. Files can be uploaded during knowledge base creation or later in the knowledge base settings.

Once indexed, the knowledge base becomes available to any agent it is connected to. Multiple agents can share the same knowledge base.

# Create Knowledge Bases

Source: https://hostman.com/docs/ai-agents/manage-knowledge-bases/create/

You can create a knowledge base when creating an agent or separately in the **Knowledge Bases** section. In both cases, the process is similar.

1.  Go to **AI Agents** → **[Knowledge Bases](https://hostman.com/my/cloud-ai/knowledge)**.
2.  Click **Create** or **Add**.
3.  Upload or link your [data sources](https://hostman.com/docs/ai-agents/manage-knowledge-bases/configure-data-sources/).
4.  An OpenSearch cloud database will be created to store the information. Choose an appropriate plan. You can [upgrade it](https://hostman.com/docs/dbaas/configuration/) later if needed.
5.  Assign a name to the knowledge base to make it easier to identify in the dashboard. You may also add an optional comment.
6.  Click **Create**.

The cloud database creation and indexing process will begin. 

The text-embedding-3-large model is used for indexing. Indexing speed depends on the file size.

# Configure Data Sources

Source: https://hostman.com/docs/ai-agents/manage-knowledge-bases/configure-data-sources/

You can manage the data sources used in a knowledge base: upload new files or remove existing ones.

## Data Source Formats

**Supported file formats**: `.csv`, `.doc`, `.docx`, `.htm`, `.html`, `.md`, `.txt`, `.xls`, `.xlsx`, `.xml`, `.pdf`.

**Maximum file size**: 50 MB per file.

-   Only textual data should be used as sources.
-   There are no content or formatting restrictions, except for tables: the first row must contain column headers.
-   Media files (images, video, etc.) will not prevent indexing, but the agent will only work with text.
-   Sources can include URLs (e.g., your own documentation or online catalogs) so the agent can provide relevant links. However, URLs are treated as text—the agent cannot read or analyze the contents of a webpage directly.
-   Specialized parsers are used for each format. For example, when processing HTML pages, scripts (JS), CSS, meta tags, and other technical elements are ignored—only page content is indexed.

## Adding a Data Source

1.  Go to **AI Services** → **Knowledge Bases**.
2.  Click on the knowledge base and open the **Data Sources** tab.
3.  Click **Add source** and choose the method:
    -   **File upload**: 
        -   Select the **Upload File** tab and add 1–100 files.

![Charming Smew 2026 08 19 13 52](https://content.hostman.com/assets/d8462d18-2c4a-403e-8668-a9c932e6a56d.png?width=1579&height=836)

-   -   **Connecting via link**:
        1.  Select the **Connect via link** tab and paste the link into the **Source link** field. You can add multiple URLs at once.
            
            URL sources requirements:
            
            -   The page must be accessible without authentication.
            -   The page must fully load via `curl`, without client-side generation (no SPA).
        2.  (Optional) Enable automatic reindexing and set up its schedule. Reindexing occurs when the ETag header changes. If no ETag is provided, the index updates at each scheduled run.
        3.  Click **Connect**. 

![Charming Smew 2026 08 19 14 00](https://content.hostman.com/assets/ce0208f5-7fec-4427-993c-0a3d75b24ec7.png?width=1582&height=839)

## Managing Data Sources

The **Data Sources** tab displays all added sources:

-   **File icon**: manually uploaded source
-   **Globe icon**: source added via URL

Hovering over a source shows the **Reindex** button, which reloads the content and updates the index:

-   **Files**: reindexes the current version
-   **URLs**: fetches the latest content from the link

![Charming Smew 2026 08 19 14 04 2026 08 19 14 05](https://content.hostman.com/assets/828ab882-fef9-4d13-932c-eb69db92be41.png?width=1578&height=782)

Clicking the three-dot menu next to a source allows you to:

-   Download the file (for manually uploaded sources)
-   Edit the URL or schedule (for linked sources)
-   Delete the source

# Choose Search Modes

Source: https://hostman.com/docs/ai-agents/manage-knowledge-bases/search-mode/

When you [connect a knowledge base to an agent](https://hostman.com/docs/ai-agents/manage-agents/connect-knowledge-base/), you can choose how it searches that base: in agentic or classic mode.

## Classic Mode

Classic mode runs a semantic search against the knowledge base before every query and adds only the retrieved fragments to the model's context.

For example, when a customer asks about the return policy, the model answers based on the company's policy document that's already been retrieved, without making any additional requests.

## Agentic Mode

Agentic mode gives the model tools to search the knowledge base on its own, so it can run additional searches whenever it needs more information. In this mode, the model can refine the query, run multiple searches in a row, and pull the answer together from different parts of the knowledge base.

This mode produces noticeably better answers, especially for complex queries, but searches can take more time and resources.

## Changing the Search Mode

You can change the search mode at any point in the agent settings:

1.  Go to **AI Services** → **Agents** and click on the required agent.
    
2.  On the **Management** tab, click **Modify** in the knowledge base block.
    
3.  Select the search mode you want.
    
4.  Save your changes.
    

![Ambitious Aquila 2026 08 20 12 48](https://content.hostman.com/assets/c2694612-3774-4a6b-b428-a90035265796.png?width=1749&height=869)

# AI Gateway

Source: https://hostman.com/docs/ai-agents/ai-gateway/

AI Gateway is an API for working directly with language models without going through AI agents.

-   [AI Gateway vs Other APIs](https://hostman.com/docs/ai-agents/ai-gateway/api-comparison/)
-   [Connecting to AI Gateway](https://hostman.com/docs/ai-agents/ai-gateway/connection/)
-   [Text Generation and Embeddings](https://hostman.com/docs/ai-agents/ai-gateway/text-generation/)
-   [Uploading and Reusing Files](https://hostman.com/docs/ai-agents/ai-gateway/files-api/)
-   [Speech Synthesis and Recognition](https://hostman.com/docs/ai-agents/ai-gateway/audio-api/)

# AI Gateway vs Other APIs

Source: https://hostman.com/docs/ai-agents/ai-gateway/api-comparison/

AI Gateway is an API for working directly with language models without going through AI agents.

Unlike the [OpenAI compatible API](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/) and the [native API](https://hostman.com/docs/ai-agents/api-usage/native-api/), AI Gateway doesn't provide agent level capabilities such as:

-   RAG
-   MCP
-   System level configuration (system prompt, temperature, response length limits)

AI Gateway is the right choice when you need to work with models directly, without any agent logic. For example:

-   You're building your own logic on top of models (custom RAG, MCP integrations)
-   You need a single access point for multiple models
-   You're already using the OpenAI SDK and want to switch between models without changing your code

#### AI Gateway vs the OpenAI Compatible API

|  | **OpenAI Compatible API** | **AI Gateway** |
| --- | --- | --- |
| **Operates on** | An agent | A model |
| **RAG / MCP** | Supported | Not supported |
| **System level settings** | Configured in the agent's dashboard | Passed with each request |
| **Model selection** | The agent's assigned model | Any available model |

We recommend using the OpenAI SDK to work with the API, it abstracts away the differences and simplifies integration.

Supported methods and capabilities depend on the model you're using. For example, the responses endpoint is only available for models that support reasoning.

AI Gateway does not support:

-   Fine-tuning for training and customizing models
-   Video API for working with video

# Connect to AI Gateway

Source: https://hostman.com/docs/ai-agents/ai-gateway/connection/

To connect to AI Gateway, go to the **AI Services → AI Gateway** section.

## Getting Connection Details

You can find the connection details in the **Connection** tab.

1.  Go to **AI Services** → **AI Gateway**.
2.  Open the **Connection** tab.
3.  Select a model and a programming language. The interface will show the input and output token pricing for the selected model. To compare model specifications before choosing, see [Comparing Models](#comparing-models).
4.  Copy the code sample for connecting and the command for installing the OpenAI library.

> [!NOTE]
> You'll need an API key to authenticate. See [Creating an API Key](#creating-an-api-key).

![AI Agents 2026 08 19 13 43](https://content.hostman.com/assets/3a79c2fc-9d14-46ed-9857-9a7b9d3e52fe.png?width=1416&height=1217)

## Comparing Models

The **Models** tab lists all available models along with their type, context window size, maximum response length, and input/output token pricing.

To find a specific model:

1.  Go to **AI Services** → **AI Gateway**.
2.  Open the **Models** tab.
3.  Filter the list by type or provider, or enter a model name in the search field.

To compare models:

1.  Go to **AI Services** → **AI Gateway**.
2.  Open the **Models** tab.
3.  Click **Compare models**.
4.  Select the models you want to compare.

![AI Agents 2026 08 26 08 03](https://content.hostman.com/assets/c503bcff-b9ca-4bba-b3a4-b086a8fae246.png?width=1588&height=868)

## Managing API Keys

### Creating an API Key

AI Gateway uses separate keys that aren't linked to your account level API keys.

> [!NOTE]
> Each API key is billed separately and costs $0.01 per month.

To create a key:

1.  Go to **AI Services** → **AI Gateway**.
2.  Click **Create Key**.
3.  Enter a name for the key and select the validity period.
4.  (Optional) Add a description that will show in the dashboard.
5.  (Optional) Select the project.
6.  Click **Create**.
7.  Copy the generated key and store it locally.

![AI Agents 2026 08 19 13 41](https://content.hostman.com/assets/6bb08c6f-19ac-4f76-bd57-4681edf137aa.png?width=1760&height=852)

### Viewing Key Usage

Each API key has its own dashboard showing incoming and outgoing token counts, token usage, and number of requests. You can filter this data by period and model.

To view key usage:

1.  Go to **AI Services** → **AI Gateway**.
    
2.  Open the **API Keys** tab.
    
3.  Click the key you want to view.
    
4.  Check token usage and number of requests on the **Dashboard** tab.
    
5.  (Optional) Filter the statistics by period or model.
    

### Setting a Token Limit

To set a token usage limit for a key:

1.  Go to **AI Services** → **AI Gateway**.
    
2.  Open the **API Keys** tab.
    
3.  Click the key you want to configure.
    
4.  On the **Management** tab, click **Set limits**.
    
5.  To set **an overall limit**:
    
    -   Enable **Common consumption limit**.
        
    -   Enter the number of tokens (input + output) allowed per day.
        
6.  To set **a limit per model**:
    
    -   Enable **Per-model consumption limit**.
        
    -   Click **Select models**.
        
    -   Choose the models to limit.
        
    -   Enter the number of tokens (input + output) allowed per day for each.
        
    -   (Optional) Click **Add limit** to set another limit.
        
7.  Click **Save**.
    

![New Key 2026 08 26 08 17 (1)](https://content.hostman.com/assets/ef688c83-7610-4288-af5c-44940d47c2f2.png?width=1755&height=869)

### Regenerating an API Key

To regenerate an existing API key:

1.  Go to **AI Services** → **AI Gateway**.
2.  Open the **API Keys** tab.
3.  Click the three dot menu next to the key you want to remove.
4.  Click **Regenerate**.
5.  Confirm the action.

![AI Agents 2026 08 19 13 42](https://content.hostman.com/assets/c2f66c7d-d353-46b3-9b80-12b6aa430bc2.png?width=1415&height=811)

### Deleting an API Key

If you no longer need an API key, you can delete it:

1.  Go to **AI Services** → **AI Gateway**.
2.  Open the **API Keys** tab.
3.  Click the three dot menu next to the key you want to remove.
4.  Click **Delete**.
5.  Confirm the action.

![AI Agents 2026 08 19 13 42](https://content.hostman.com/assets/c2f66c7d-d353-46b3-9b80-12b6aa430bc2.png?width=1415&height=811)

# Text Generation and Embeddings

Source: https://hostman.com/docs/ai-agents/ai-gateway/text-generation/

We recommend using the OpenAI SDK to work with AI Gateway, it removes the need to send raw HTTP requests and makes integration much simpler.

Available SDKs:

-   [Python](https://github.com/openai/openai-python)
-   [Node.js](https://github.com/openai/openai-node)
-   [Java](https://github.com/openai/openai-java)
-   [Go](https://github.com/openai/openai-go)

The full list of SDKs is available in the [OpenAI repository](https://github.com/orgs/openai/repositories).

To follow this guide, you'll need to [create an AI Gateway API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key). 

The examples below use Python and the `openai` library. Install it with `pip`:

```shell
pip install openai
```

## Sending a Request

Use the `Chat Completions` method to send messages. Messages are passed in the `messages` array.

Each message contains:

-   `role`: the [sender's role](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#roles) (`user`, `assistant`, `system`)
-   `content`: the message text

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Answer briefly and to the point.",
        },
        {
            "role": "user",
            "content": "Explain what Kubernetes is",
        },
    ],
)

print(response.choices[0].message.content)
```

Parameters:

-   `api_key`: your AI Gateway API key. Replace this with your own key.
-   `base_url`: the base URL for connecting to AI Gateway.
-   `model`: the name of the model you want to use.
-   `messages`: an array of messages with roles and text.

## Sending a Request With Message History

To preserve conversation context, pass previous messages in the `messages` array:

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.chat.completions.create(
    model="MODEL_NAME",
    messages=[
        {
            "role": "system",
            "content": "Reply only in short phrases.",
        },
        {
            "role": "user",
            "content": "What's 2 + 5?",
        },
        {
            "role": "assistant",
            "content": "7",
        },
        {
            "role": "user",
            "content": "Now multiply the result by 2",
        },
    ],
)

print(response.choices[0].message.content)
```

In this example, previous messages (`assistant` and `user`) are included to preserve the conversation context.

## Sending a Request (Responses API)

The `Responses API` is a newer way to work with models. It simplifies the request structure and doesn't require building a `messages` array explicitly.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Answer briefly and to the point.",
    input="Explain what Kubernetes is"
)

print(response.output_text)
```

Parameters:

-   `model`: the name of the model you want to use
-   `instructions`: instructions for the model (similar to a system prompt)
-   `input`: the request text

## Sending a Request With Message History (Responses API)

To preserve conversation context with the `Responses API`, pass `previous_response_id`, which is the ID of the previous response.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.responses.create(
    model="MODEL_NAME",
    instructions="Reply only in short phrases.",
    input="What's 2 + 5?"
)

next_response = client.responses.create(
    model="MODEL_NAME",
    instructions="Reply only in short phrases.",
    previous_response_id=response.id,
    input="Now multiply the result by 2"
)

print(next_response.output_text)
```

In this example, the first request returns a response object containing a unique `id`. This `id` is passed as `previous_response_id` in the next request, letting you continue the conversation without sending the full message history again.

The `model` parameter must be specified in every request, including follow up calls that use `previous_response_id`.

## Listing Available Models

AI Gateway lets you retrieve a list of available models:

```shell
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

models = client.models.list()

for model in models.data:
    print(model.id)
```

The `models.list()` method returns a list of models you can use in the `model` parameter.

## Using Embeddings

Embeddings convert text into a vector representation. This is useful for semantic search, clustering, or RAG.

AI Gateway provides the `openai/text-embedding-3-large` model for creating embeddings.

```py
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://ai-api.hostman.com/v1"
)

response = client.embeddings.create(
    model="openai/text-embedding-3-large",
    input="Text to vectorize",
)

print(response.data[0].embedding)
```

The method returns a vector representation of the input text.

# Uploading and Reusing Files

Source: https://hostman.com/docs/ai-agents/ai-gateway/files-api/

The Files API lets you upload files to AI Gateway and reference them in requests to models. This is useful when a model needs to work with a document, spreadsheet, text file, or other material that you don't want to paste into the request body every time.

You upload a file once, and AI Gateway returns a file identifier. You can then reuse this identifier in subsequent requests to the model.

## Setting Up Your Token

To use the Files API, you'll need to [create an AI Gateway API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key). 

The examples below use an environment variable called `HOSTMAN_AI_TOKEN` so you don't have to paste your key into every request. On Linux and macOS, you can set it with:

```shell
export HOSTMAN_AI_TOKEN="your_API_key"
```

This makes the variable available for the current terminal session. If you want it to persist across terminal restarts, add the same line to your shell's configuration file — for example, `~/.zshrc` for zsh or `~/.bashrc` for bash.

## API Methods

Below are the available methods for working with files through the API. Requests targeting an already-uploaded file use its `file_id`, which is returned when the file is uploaded.

### Uploading a File

To upload a file, send a POST request to the `/v1/files` endpoint:

```shell
curl --request POST \
 --url https://ai-api.hostman.com/v1/files \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@<file_path>" \
 --form "target_model_names=openai/gpt-4.1"
```

Parameters:

-   `purpose`: The purpose of the file. AI Gateway supports only `user_data` and `messages`. Use `user_data` for files used in model requests, and `messages` for files used with Claude models. Other values for purpose aren't supported.
    
-   `file`: The path to your local file, prefixed with `@`. For example, `file=@/Users/hostman/test.txt`.
    
-   `target_model_names`: The models the file should be available to. To make a file available to several models, list them separated by commas, for example, `target_model_names=openai/gpt-4.1,openai/gpt-5`. You can [find the correct model names](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) in the **Connection** tab under **AI Gateway**.
    

An uploaded file is only available to the model specified in the model parameter.

Example response:

```shell
{
 "id": "file-bGl0ZWxsbTpmaWxlLUdmMWRD1mDEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "testfile.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}
```

Use the value of the `id` field for any further operations with this file.

### Getting File Information

This method retrieves the metadata of an uploaded file:

```shell
curl --request GET \
 --url https://ai-api.hostman.com/v1/files/<file_id> \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN"
```

Here, `file_id` is the file identifier returned when the file was uploaded.

### Retrieving File Content

The `/content` method exists for compatibility with the Files API and for future scenarios:

```shell
curl --request GET \
 --url https://ai-api.hostman.com/v1/files/<file_id>/content \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN"
```

Retrieving content is only available for certain purpose values, such as fine-tuning workflows. These scenarios aren't currently supported in AI Gateway. For files with `purpose=user_data` or `purpose=messages`, this method isn't used to read file content.

### Deleting a File

To delete a file, send a `DELETE` request:

```shell
curl --request DELETE \
 --url https://ai-api.hostman.com/v1/files/<file_id> \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN"
```

Once deleted, a file's identifier can no longer be used in requests to a model.

## Example: Working With a File

Let's walk through an example of uploading a text file, `test.txt`, located at `/Users/hostman/test.txt`.

```shell
curl --request POST \
 --url https://ai-api.hostman.com/v1/files \
 --header "authorization: Bearer $HOSTMAN_AI_TOKEN" \
 --header "content-type: multipart/form-data" \
 --form purpose=user_data \
 --form "file=@/Users/hostman/test.txt" \
 --form "target_model_names=openai/gpt-4.1"
```

The `file` parameter here specifies the full path to the file on your local machine. If the file is in your terminal's current directory, you can use a relative path instead, such as `file=@test.txt`.

Example response:

```shell
{
 "id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI",
 "bytes": 27,
 "created_at": 1782804439,
 "filename": "test.txt",
 "object": "file",
 "purpose": "user_data",
 "status": "processed",
 "expires_at": null,
 "status_details": null
}
```

Once uploaded, you can pass the file to a model through the Responses API. To do this, include an object with the type `input_file` in your request, with the `file_id` field set to the identifier from the upload response:

```shell
curl https://ai-api.hostman.com/v1/responses \
 --header "Content-Type: application/json" \
 --header "Authorization: Bearer $HOSTMAN_AI_TOKEN" \
 --data '{
   "model": "openai/gpt-4.1",
   "input": [
     {
       "role": "user",
       "content": [
         {
           "type": "input_text",
           "text": "Read the uploaded file and briefly summarize its contents."
         },
         {
           "type": "input_file",
           "file_id": "file-bGl0ZWxsbTpmaWxlL87mMWRDV7NEZEtEOGZqQ1BBWjlxWk47bW9kZWwsb3BlbmFpL2dwdC00LjE7bGl0ZWxsbV9vd25lcl91c2VyX2lkLG50OTQ1NDI"
         }
       ]
     }
   ]
 }'
```

The model specified in this request must match the model the file was originally uploaded for.

# Speech Synthesis and Recognition

Source: https://hostman.com/docs/ai-agents/ai-gateway/audio-api/

AI Gateway offers models for speech synthesis and speech recognition. You can use them to convert text into spoken audio, add voice responses to your applications, transcribe calls, and turn other audio recordings into text.

For speech synthesis, or TTS (Text-to-Speech), AI Gateway provides the `openai/gpt-4o-mini-tts` model.

For speech recognition, or STT (Speech-to-Text), you can use `openai/gpt-4o-mini-transcribe` and `openai/gpt-4o-transcribe`.

## Speech Synthesis Capabilities

The `openai/gpt-4o-mini-tts` model generates audio from text you provide. It supports different languages and lets you control how the speech sounds using an instruction—for example, setting the pace, intonation, emotional tone, or overall style.

You can choose from the following voices:

-   `alloy`
-   `ash`
-   `ballad`
-   `coral`
-   `echo`
-   `fable`
-   `nova`
-   `onyx`
-   `sage`
-   `shimmer`
-   `verse`
-   `marin`
-   `cedar`

You can listen to samples of each voice on [OpenAI.fm](https://openai.fm/).

The following audio formats are supported:

-   `mp3`: the default format
-   `opus`: suited for streaming and voice communication
-   `aac`: a compressed format commonly used on mobile devices
-   `flac`: lossless compression
-   `wav`: uncompressed audio
-   `pcm`: raw audio data with no file header

The `wav` and `pcm` formats work well for use cases where low latency matters. AI Gateway also supports streaming, so playback can start before the entire audio file has finished generating.

## Transcription Capabilities

The `openai/gpt-4o-mini-transcribe` and `openai/gpt-4o-transcribe` models convert speech from an audio file into text. You can either let the model detect the language automatically or specify it explicitly in the request.

Transcription supports the following file formats: `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, and `webm`. You can get the result back as JSON or as plain text.

You can also pass a prompt parameter with additional context in your request. This helps the model correctly recognize:

-   first and last names
-   product and company names
-   abbreviations
-   professional or technical terms
-   words that are hard to identify from pronunciation alone

If a recording is split into several chunks, you can pass the text of the previous chunk in the prompt parameter. This helps the model keep context between requests.

## How Tokens Are Counted

Audio models count both text tokens and audio tokens. Text tokens depend on the amount of text involved, while audio tokens depend on the length of the audio.

For speech synthesis (TTS models):

-   `input_tokens`: text tokens from the input text
-   `output_tokens`: audio tokens from the generated recording. One second of audio counts as one audio token.

For example, if the model generates four seconds of audio, that's four output audio tokens. The number of input text tokens depends on the length of the source text.

For transcription (STT models):

-   `input_tokens`: audio tokens from the source recording, roughly 10 tokens per second
-   `output_tokens`: text tokens from the transcript

For example, a 10-second recording uses roughly 100 input audio tokens. The number of output text tokens depends on the length of the transcript.

## Limitations And Notes

-   Audio models are only available through AI Gateway.
-   Streaming generation and playback are only supported for TTS.
-   Real-time transcription from a microphone isn't supported.
-   Transcription responses are available in JSON or plain text format.

## Getting Started

To use the audio models, you'll need to [create an AI Gateway API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key). 

The examples below use an environment variable called `HOSTMAN_AI_TOKEN` so you don't have to paste your key directly into your code. On Linux and macOS, you can set it with:

```shell
export HOSTMAN_AI_TOKEN="your_API_key"
```

Install the OpenAI library:

```shell
pip install openai
```

Create a client and point it to the AI Gateway base URL:

```py
import os

from openai import OpenAI

client = OpenAI(
   api_key=os.environ["HOSTMAN_AI_TOKEN"],
   base_url="https://ai-api.hostman.com/v1",
)
```

## Speech Synthesis

Speech synthesis uses the `audio.speech.create()` method.

### Generating an Audio File

In the example below, the model converts text to speech and saves the result to a file called `speech.mp3`:

```py
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
   api_key=os.environ["HOSTMAN_AI_TOKEN"],
   base_url="https://ai-api.hostman.com/v1",
)

speech_file = Path("speech.mp3")

with client.audio.speech.with_streaming_response.create(
   model="openai/gpt-4o-mini-tts",
   voice="shimmer",
   input="Hello! This is a speech synthesis test.",
   instructions="Speak in a calm and friendly tone.",
   response_format="mp3",
) as response:
   response.stream_to_file(speech_file)
```

Parameters:

-   `model`: the speech synthesis model to use
-   `voice`: the voice used to read the text
-   `input`: the text to convert to speech
-   `instructions`: an instruction describing the speaking style
-   `response_format`: the format of the generated audio

### Streaming Playback

To start playback before generation finishes, use the `async` client together with `LocalAudioPlayer`.

To use `LocalAudioPlayer`, install the `numpy` and `sounddevice` libraries:

```shell
pip install numpy sounddevice
```

Example of streaming playback:

```py
import asyncio
import os

from openai import AsyncOpenAI
from openai.helpers import LocalAudioPlayer

client = AsyncOpenAI(
   api_key=os.environ["HOSTMAN_AI_TOKEN"],
   base_url="https://ai-api.hostman.com/v1",
)

async def main() -> None:
   async with client.audio.speech.with_streaming_response.create(
       model="openai/gpt-4o-mini-tts",
       voice="shimmer",
       input="Hello! This is a streaming speech synthesis test.",
       response_format="pcm",
   ) as response:
       await LocalAudioPlayer().play(response)

if __name__ == "__main__":
   asyncio.run(main())
```

This example uses the `pcm` format, which lets you play the audio as it's received from the model.

## Audio Transcription

Transcription uses the `audio.transcriptions.create()` method.

### Transcribing a File

In the example below, the model transcribes English speech from a file called `audio.mp3`:

```py
import os

from openai import OpenAI

client = OpenAI(
   api_key=os.environ["HOSTMAN_AI_TOKEN"],
   base_url="https://ai-api.hostman.com/v1",
)

with open("audio.mp3", "rb") as audio_file:
   transcription = client.audio.transcriptions.create(
       model="openai/gpt-4o-mini-transcribe",
       file=audio_file,
       language="en",
       response_format="json",
   )

print(transcription.text)
```

Parameters:

-   `model`: the transcription model to use
-   `file`: the audio file to convert to text
-   `language`: the language of the audio. If not specified, the model detects it automatically.
-   `response_format`: the response format—json or text

### Passing Context

You can use the `prompt` parameter to give the model relevant terms, extra context, and requirements for the output. You can also ask it to remove filler words:

```py
import os
from openai import OpenAI

client = OpenAI(
   api_key=os.environ["HOSTMAN_AI_TOKEN"],
   base_url="https://ai-api.hostman.com/v1",
)

with open("meeting.mp3", "rb") as audio_file:
   transcription = client.audio.transcriptions.create(
       model="openai/gpt-4o-transcribe",
       file=audio_file,
       language="en",
       response_format="json",
       prompt=(
           "The recording is about Kubernetes and cloud infrastructure. "
           "The conversation mentions Hostman, kubectl, and Ingress. "
           "Remove filler words and interjections from the transcript. "
           "Keep the meaning intact and don't paraphrase the rest of the speech."
       ),
   )

print(transcription.text)
```

In this example, `prompt` helps the model recognize technical terms and sets requirements for the final text. This parameter doesn't replace the audio content—it adds context and instructions on top of it.

### Transcribing Audio From a Microphone

AI Gateway doesn't support real-time transcription. To get results close to real time, you can record audio in short chunks and send each chunk to the API separately.

Install the additional libraries:

```shell
pip install numpy sounddevice
```

The example below records audio in three-second chunks. A small overlap is added between adjacent chunks so the model doesn't lose words at the boundary between recordings:

```py
import io
import os
import queue
import threading
import time
import wave
from dataclasses import dataclass

import numpy as np
import sounddevice as sd
from openai import OpenAI

MODEL = "openai/gpt-4o-mini-transcribe"

SAMPLE_RATE = 16_000
CHANNELS = 1
SAMPLE_WIDTH_BYTES = 2

CHUNK_SECONDS = 3.0
OVERLAP_SECONDS = 0.4
FRAMES_PER_BLOCK = 1_600

client = OpenAI(
   api_key=os.environ["HOSTMAN_AI_TOKEN"],
   base_url="https://ai-api.hostman.com/v1",
)

@dataclass
class AudioChunk:
   index: int
   pcm_data: bytes

audio_queue: queue.Queue[AudioChunk | None] = queue.Queue(maxsize=10)
stop_event = threading.Event()

def pcm_to_wav_bytes(pcm_data: bytes) -> io.BytesIO:
   wav_buffer = io.BytesIO()

   with wave.open(wav_buffer, "wb") as wav_file:
       wav_file.setnchannels(CHANNELS)
       wav_file.setsampwidth(SAMPLE_WIDTH_BYTES)
       wav_file.setframerate(SAMPLE_RATE)
       wav_file.writeframes(pcm_data)

   wav_buffer.seek(0)
   wav_buffer.name = "chunk.wav"

   return wav_buffer

def transcription_worker() -> None:
   while True:
       chunk = audio_queue.get()

       if chunk is None:
           audio_queue.task_done()
           break

       try:
           wav_file = pcm_to_wav_bytes(chunk.pcm_data)
           started_at = time.perf_counter()

           transcription = client.audio.transcriptions.create(
               model=MODEL,
               file=wav_file,
               language="en",
               response_format="json",
           )

           elapsed = time.perf_counter() - started_at
           text = getattr(transcription, "text", "").strip()

           if text:
               print(
                   f"\n[{chunk.index:04d}] "
                   f"({elapsed:.2f} sec.) {text}",
                   flush=True,
               )
           else:
               print(
                   f"\n[{chunk.index:04d}] "
                   f"({elapsed:.2f} sec.) [silence]",
                   flush=True,
               )

       except Exception as exc:
           print(
               f"\nError transcribing chunk "
               f"{chunk.index}: {exc}",
               flush=True,
           )

       finally:
           audio_queue.task_done()


def record_microphone() -> None:
   chunk_samples = int(SAMPLE_RATE * CHUNK_SECONDS)
   overlap_samples = int(SAMPLE_RATE * OVERLAP_SECONDS)

   accumulated = np.empty(0, dtype=np.int16)
   previous_tail = np.empty(0, dtype=np.int16)
   chunk_index = 1

   print("Speak now. Press Ctrl+C to stop.")

   with sd.InputStream(
       samplerate=SAMPLE_RATE,
       channels=CHANNELS,
       dtype="int16",
       blocksize=FRAMES_PER_BLOCK,
   ) as stream:
       while not stop_event.is_set():
           block, overflowed = stream.read(FRAMES_PER_BLOCK)

           if overflowed:
               print("\nWarning: audio buffer overflow.")

           accumulated = np.concatenate((accumulated, block[:, 0]))

           while len(accumulated) >= chunk_samples:
               current_samples = accumulated[:chunk_samples]
               accumulated = accumulated[chunk_samples:]

               if len(previous_tail) > 0:
                   samples_to_send = np.concatenate(
                       (previous_tail, current_samples)
                   )
               else:
                   samples_to_send = current_samples

               if overlap_samples > 0:
                   previous_tail = current_samples[-overlap_samples:].copy()
               else:
                   previous_tail = np.empty(0, dtype=np.int16)

               audio_chunk = AudioChunk(
                   index=chunk_index,
                   pcm_data=samples_to_send.astype(
                       "<i2",
                       copy=False,
                   ).tobytes(),
               )

               try:
                   audio_queue.put(audio_chunk, timeout=1)
                   print(".", end="", flush=True)
               except queue.Full:
                   print(
                       "\nQueue full: chunk skipped. "
                       "Increase CHUNK_SECONDS or check API speed."
                   )

               chunk_index += 1

       if len(accumulated) >= SAMPLE_RATE // 2:
           if len(previous_tail) > 0:
               accumulated = np.concatenate(
                   (previous_tail, accumulated)
               )

           audio_queue.put(
               AudioChunk(
                   index=chunk_index,
                   pcm_data=accumulated.astype(
                       "<i2",
                       copy=False,
                   ).tobytes(),
               )
           )


def main() -> None:
   worker = threading.Thread(
       target=transcription_worker,
       daemon=True,
   )
   worker.start()

   try:
       record_microphone()
   except KeyboardInterrupt:
       print("\nStopping recording...")
       stop_event.set()
   finally:
       audio_queue.put(None)
       audio_queue.join()
       worker.join(timeout=5)
       print("Done.")


if __name__ == "__main__":
   main()
```

You can adjust the `CHUNK_SECONDS` and `OVERLAP_SECONDS` values. Shorter chunks reduce latency but increase the number of requests. Because of the overlap, some words may repeat in the result—remove these duplicates during further text processing if needed.

# API Usage

Source: https://hostman.com/docs/ai-agents/api-usage/

We support three types of API for working with AI agents and models:

-   [OpenAI-compatible API](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/): suitable for integration with external libraries and UIs, using the standard request structure.
    
-   [Native API](https://hostman.com/docs/ai-agents/api-usage/native-api/): simpler and easier to use, especially when a quick result is needed without external dependencies.
    
-   [AI Gateway](https://hostman.com/docs/ai-agents/ai-gateway/): for working directly with models without using AI agents.

## Key Differences

| **Feature** | **OpenAI compatible API** | **Native API** | **AI Gateway** |
| --- | --- | --- | --- |
| Object of operation | An agent | An agent | A model |
| Request format | `messages[]` | `message` + `parentMessageId` | `messages[]`, `responses` |
| Message history | Sent with the request | Stored | Sent with the request |
| RAG / MCP | Supported | Supported | Not supported |
| Model settings | Via the agent's dashboard | Via request parameters | Sent with each request |
| Model selection | Limited to the agent's model | Limited to the agent's model | Any available model |
| Streaming responses | Supported | Not supported | Supported |

## Which API to Choose

**Use the OpenAI-compatible API if you:**

-   Want to integrate the agent with external libraries (e.g., LangChain, Open WebUI)
-   Already use OpenAI and want to simply replace the URL
-   Need usage statistics (tokens, model)
-   Require streaming responses
-   Plan to use multimodal messages

**Use the Native API if you:**

-   Need built-in message history without explicitly passing context
-   Are building a simple app with minimal external dependencies
-   Want responses in a simple format
-   Need fast and lightweight integration, for example, for an MVP

**Use AI Gateway if you:**

-   Need to work directly with models without agent logic
-   Are building your own logic (e.g., RAG or request routing)
-   Need access to multiple models through a single API
-   Are using the OpenAI SDK and want to switch between models without changing your code

# Native API

Source: https://hostman.com/docs/ai-agents/api-usage/native-api/

You can interact with AI agents using the Native API.

## Authentication

Each request must include [the API token](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/). 

The token is passed in the following format:

```shell
--header "authorization: Bearer $TOKEN"
```

In cURL examples, you can:

-   Provide the token manually by replacing `$TOKEN` with your actual token in each request, or
-   Use an environment variable so you don’t have to insert the token every time:

```shell
export TOKEN=your_access_token
```

In this case, the `$TOKEN` variable will be automatically substituted.

In Python and Node.js examples, the token is specified directly in the code as `{{token}}`. We recommend storing it in environment variables or configuration files rather than in code to prevent leaks.

## Agent Access ID

To interact with an agent, you also need its **Access ID**, which can be found in the agent's **Dashboard** tab.

![7aedefc8 8a23 4372 99b5 4d0f39c9396e](https://content.hostman.com/assets/e3f387f9-c157-431e-9631-68325398cda6.png?width=1560&height=1410)

## Agent Configuration

When using the Native API, the agent uses the settings [defined in the Playground](https://hostman.com/docs/ai-agents/manage-agents/playground/).

## Sending a Message to the Agent

This method allows you to send a message to the AI agent and receive a response.

**Request**:

```shell
POST /api/v1/cloud-ai/agents/{access_id}/call
```

**cURL:**

```shell
curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/<access_id>/call \
  --header "authorization: Bearer $TOKEN" \
  --header "content-type: application/json" \
  --data '{ "message": "Hello!", "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24" }'
```

**Python:**

```py
import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/<access_id>/call"

payload = {
    "message": "Hi",
    "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}
headers = {
    "content-type": "application/json",
    "authorization": "Bearer {{token}}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**Node.js:**

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/<access_id>/call',
  headers: {'content-type': 'application/json', authorization: 'Bearer {{token}}'},
  body: {message: 'Hi', parent_message_id: '3adfea84-bcdb-44b5-8914-92035e75ec24'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

**Parameters:**

-   `message`: the text of the message to the agent
-   `parent_message_id`: optional. The ID of a message to continue a conversation. Can be the last message or any other message ID from the chat

**Example Response**:

```shell
{
  "message": "agent's reply",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}
```

The `id` value in the response can be used as `parent_message_id` in subsequent requests.

The `finish_reason` field indicates why the response generation ended. Possible values:

-   `stop`: response was fully generated without errors.
-   `length`: response exceeded the [maximum token limit](https://hostman.com/docs/ai-agents/manage-agents/playground/#modify-agent-settings), generation was cut off.
-   `content_filter`: a filter from the AI provider (e.g., OpenAI, xAI) triggered, stopping generation. Filters may include content moderation by the provider.
-   `error`: an error occurred during generation. To investigate, contact the support and include the response body.

# OpenAI-compatible API

Source: https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/

The OpenAI-compatible API provides a unified request and response structure for different AI providers. Instead of dealing with dozens of different formats, you work with a single standard that is compatible with SDKs, libraries, and UIs.

## Why Unification Matters

Consider two native APIs: `agent.hostman.com` and a hypothetical `api.somerandomai.com`. Let’s see how message sending is implemented.

![1](https://content.hostman.com/assets/717b6164-3d05-4a1f-ab79-649fb810c381.png?width=1316&height=1004)

Even for the same task, request structures can differ significantly. For example, one API uses `parent_message_id` to maintain context, while another uses a nested object:

```shell
"context": {
 "thread_id": "abc123",
 "reply_to": "msg789"
}
```

Additionally, with our API, settings are configured via a separate request, whereas in the third-party API, they are included in the settings object with every message.

As a result, you would need to:

-   Write a separate client for each API
-   Learn each API’s field names and behavior
-   Test everything from scratch

The OpenAI-compatible API solves this problem. The structure is always the same: a `messages` array with `role` and `content` fields, plus standard parameters (`model`, `temperature`, `max_tokens`). Differences remain only in the URL and model name.

![2](https://content.hostman.com/assets/fde9ce44-71bf-44e4-9de5-85c8368b5246.png?width=1568&height=1218)

**Benefits**:

-   Fast integration with any software supporting the OpenAI API
-   Support for popular libraries (e.g., LangChain)
-   Works with ready-made UIs (e.g., [Open WebUI](https://hostman.com/docs/ai-agents/api-usage/open-webui/))
-   Minimal effort when migrating from OpenAI

## Limitations

The current implementation is not fully OpenAI-compatible.

**Not supported:**

-   **Embeddings**: the `/v1/embeddings` endpoint is unavailable
-   **Fine-tuning**: training and customization of models
-   **Images API**: image generation
-   **Audio API**: speech-to-text and text-to-speech conversion (except for audio messages in chat)
-   **Files API**: file upload and management
-   **Assistants API**: creation and management of assistants
-   **Web search**: searching and retrieving data from the internet

**Implementation notes:**

-   The `model` parameter in requests is ignored, the model defined in the agent settings is used.
-   Some parameters may be ignored depending on the agent’s selected model.
-   The [prompt defined in the agent’s settings](https://hostman.com/docs/ai-agents/manage-agents/prompts/) is applied to requests without explicit prompts.

## Usage

Let’s look at how to use the OpenAI-compatible API.

> [!NOTE]
> You can find all available API methods [in the documentation](https://agent.hostman.com/docs/).

### Authentication

An [API token](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/) is required for requests.

Include the token in the request header:

```shell
Authorization: Bearer $TOKEN
```

In cURL examples, you can:

-   Provide the token manually by replacing `$TOKEN` with your actual token in each request, or
-   Use an environment variable to avoid inserting it every time:

```shell
export TOKEN=your_access_token
```

The `$TOKEN` variable will then be automatically substituted.

In Python and Node.js examples, the token is represented as `{{token}}`. We recommend storing it in environment variables or configuration files instead of in code to prevent leaks.

### Base URL

The API also requires a base URL, which can be found in the agent's **Dashboard** tab.

![9b7115d2 3895 4087 9d62 Fa964eed8d19](https://content.hostman.com/assets/c424c212-63bf-4019-9219-44cb2787635c.png?width=1560&height=1410)

### Sending Messages to the Agent

Two methods are supported: Chat Completions and Text Completions. The Text Completions method is deprecated and only maintained for backward compatibility; it is not recommended.

#### Chat Completions Usage Example

```shell
POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions
```

**cURL:**

```shell
curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{ "model": "gpt-4.1", "messages": [ { "role": "user", "content": "Hello!" } ], "temperature": 1, "max_tokens": 100, "stream": false }'
```

**Python:**

```py
import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions"

payload = {
    "model": "gpt.1",
    "messages": [
        {
            "role": "user",
            "content": "Hello!"
        }
    ],
    "temperature": 1,
    "max_tokens": 100,
    "stream": False
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**Node.js:**

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    model: 'gpt.1',
    messages: [{role: 'user', content: 'Hello!'}],
    temperature: 1,
    max_tokens: 100,
    stream: false
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

**Parameters**:

-   `model`: optional, ignored (for compatibility)
-   `messages`: array of messages:
    -   `role`: [sender role](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#roles) (`user`, `assistant`, `system`)
    -   `content`: message text
-   `temperature`: creativity of the response
-   `max_tokens`: response length limit
-   `stream`: stream output (true/false)

> [!NOTE]
> For GPT-5 models, `max_tokens` is replaced with `max_completion_tokens`, and using `temperature` will trigger an error.

Additional parameters may vary depending on the model. When constructing a request, refer to the parameters available in the dashboard for the selected model: if a parameter is present in the panel, it is supported when accessed through the API.

**Example Response:**

```shell
{
  "id": "fc8cd652-af12-4a89-8ef7-490a0526e8d3",
  "object": "chat.completion",
  "created": 1757601532,
  "model": "gpt-4.1",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you? 😊"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}
```

#### Text Completions Usage Example

```shell
POST /api/v1/cloud-ai/agents/{{agent_id}}/v1/completions
```

**cURL:**

```shell
curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{ "prompt": "Hello!", "model": "gpt-4.1", "max_tokens": 100, "temperature": 0.7, "top_p": 0.9, "n": 1, "stream": false, "logprobs": null, "echo": false, "stop": [ "\n" ], "presence_penalty": 0, "frequency_penalty": 0, "best_of": 1, "user": "hostman" }'
```

**Python:**

```py
import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions"

payload = {
    "prompt": "Hello!",
    "model": "4.1",
    "max_tokens": 100,
    "temperature": 0.7,
    "top_p": 0.9,
    "n": 1,
    "stream": False,
    "logprobs": None,
    "echo": False,
    "stop": [" "],
    "presence_penalty": 0,
    "frequency_penalty": 0,
    "best_of": 1,
    "user": "hostman"
}
headers = {
    "authorization": "Bearer {{token}}",
    "content-type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**Node.js:**

```js
const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/completions',
  headers: {authorization: 'Bearer {{token}}', 'content-type': 'application/json'},
  body: {
    prompt: 'Hello!',
    model: 'gpt-4.1',
    max_tokens: 100,
    temperature: 0.7,
    top_p: 0.9,
    n: 1,
    stream: false,
    logprobs: null,
    echo: false,
    stop: ['\n'],
    presence_penalty: 0,
    frequency_penalty: 0,
    best_of: 1,
    user: 'hostman'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
```

**Parameters**:

-   `prompt`: text of the request
-   `model`: ignored, included for compatibility
-   `max_tokens`: response length limit
-   `temperature`: creativity level
-   `top_p`: probability sampling
-   `n`: number of responses (ignored)
-   `stream`: stream output

Other parameters (`logprobs`, `echo`, `stop`, `presence_penalty`, `frequency_penalty`, `best_of`, `user`) are partially supported, mainly for compatibility.

**Example Response:**

```shell
{
  "id": "7f967459-428c-46ad-87f0-213ff951024d",
  "object": "text_completion",
  "created": 1757601892,
  "model": "gpt-4.1",
  "choices": [
    {
      "text": "Hello! How can I help you? 😊",
      "index": 0,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  },
  "response_id": "ea9aa124-0c51-467c-9ab6-218ab4ec65e7"
}
```

## Roles

In Chat Completions, each message includes a role. There are three roles:

-   `user`: user request
-   `assistant`: AI response
-   `system`: system prompt

### user

The `user` role is used to send regular user requests to the AI.

Example:

```shell
 {
  "role": "user",
  "content": "What is 2+5?"
}
```

### assistant

This role indicates the AI’s reply to a previous message.

> [!NOTE]
> Important: In OpenAI-compatible API, dialogue history must be included in every request. Include both `user` requests and `assistant` responses to maintain context.

Example:

```shell
curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "What is 2+5? Provide only the answer, no formatting." },
      { "role": "assistant", "content": "7" },
      { "role": "user", "content": "Now multiply the result by 2. Provide only the answer, no formatting." }
    ]
  }'
```

The request passes the previous question and answer, marking messages as `"role": "user"` or `"role": "assistant"`. The last user message is left without a response; this is what the model will generate a new answer for.

**Example Response:**

```shell
{
  "index": 0,
  "message": {
    "role": "assistant",
    "content": "14",
    "refusal": null,
    "annotations": []
  },
  "finish_reason": "stop"
}
```

### system

The `system` role defines the agent’s behavior: style, tone, constraints, and goals. It is usually the first message in the `messages` array. See the article on [system prompts](https://hostman.com/docs/ai-agents/manage-agents/prompts/) for details.

Looking at the example of using the `assistant` role, you can notice that the instruction is repeated in the user requests:

```shell
Provide only the answer, no formatting
```

This duplication can be avoided by specifying the instruction once in the system prompt.

Example:

```shell
curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions \
  --header 'authorization: Bearer $TOKEN' \
  --header 'content-type: application/json' \
  --data '{
    "model": "gpt-4",
    "messages": [
      { "role": "system", "content": "When answering questions, provide only the calculation result, without any formatting." },
      { "role": "user", "content": "What is 2+5?" },
      { "role": "assistant", "content": "7" },
      { "role": "user", "content": "Now multiply the result by 2" }
    ]
  }'
```

Now the model will follow the instruction even if it’s not repeated in every user message.

# Open WebUI

Source: https://hostman.com/docs/ai-agents/api-usage/open-webui/

Open WebUI is a convenient chat interface for models accessible via API. It allows interaction with AI agents in a familiar dialogue format.

This guide explains how to install Open WebUI and connect it to an AI agent.

The guide assumes that you have already [created an AI agent](https://hostman.com/docs/ai-agents/manage-agents/create/). 

## Installation

Open WebUI can be deployed locally on your workstation or on a remote server for continuous access to the chat.

**Minimum requirements**: 2 GB of RAM.

Ensure that Docker and Docker Compose are installed:

```shell
docker --version
docker compose version
```

### Local Deployment

To deploy Open WebUI locally, create a `docker-compose.yaml` file with the following content:

```shell
services:
  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
volumes:
  open-webui:
```

### Server Deployment

If deploying on a server for easier access, it is recommended to use a domain and SSL certificate. Create a `.env` file with the following variables:

```shell
DOMAIN=openwebui.example.com
LETSENCRYPT_EMAIL=admin@example.com
TZ=Europe/Cyprus
```

-   `DOMAIN`: the domain where Open WebUI will be accessible. Ensure the domain’s A record points to your server.
-   `LETSENCRYPT_EMAIL`: the email address used for issuing an SSL certificate.
-   `TZ`: the server’s timezone.

Then, create a `docker-compose.yaml` file with the following content:

```shell
version: "3.8"

services:
  traefik:
    image: traefik:v3.1
    container_name: traefik
    restart: unless-stopped
    command:
      - "--providers.docker=true"
      - "--providers.docker.exposedbydefault=false"
      - "--entrypoints.web.address=:80"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.myresolver.acme.httpchallenge=true"
      - "--certificatesresolvers.myresolver.acme.httpchallenge.entrypoint=web"
      - "--certificatesresolvers.myresolver.acme.email=${LETSENCRYPT_EMAIL}"
      - "--certificatesresolvers.myresolver.acme.storage=/letsencrypt/acme.json"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - "/var/run/docker.sock:/var/run/docker.sock:ro"
      - "letsencrypt:/letsencrypt"

  openwebui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: openwebui
    restart: unless-stopped
    environment:
      - TZ=${TZ}
      - WEBUI_URL=https://${DOMAIN}
    volumes:
      - openwebui-data:/app/backend/data
    labels:
      - "traefik.enable=true"

      # HTTPS router
      - "traefik.http.routers.openwebui.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.openwebui.entrypoints=websecure"
      - "traefik.http.routers.openwebui.tls.certresolver=myresolver"
      - "traefik.http.services.openwebui.loadbalancer.server.port=8080"
      - "traefik.http.services.openwebui.loadbalancer.server.scheme=http"

      # HTTP router redirecting to HTTPS
      - "traefik.http.routers.openwebui-http.rule=Host(`${DOMAIN}`)"
      - "traefik.http.routers.openwebui-http.entrypoints=web"
      - "traefik.http.routers.openwebui-http.middlewares=redirect-to-https"

      # Middleware for redirecting
      - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https"

volumes:
  openwebui-data:
  letsencrypt:
```

Save the manifest and start the container:

```shell
docker compose up
```

Docker will download the image and deploy Open WebUI. Once the logo appears in the terminal, open your browser at `http://localhost:3000/` (or use your domain if deployed on a server).

If the welcome page loads, the installation was successful.

Return to the terminal and stop the container with Ctrl+C, then restart it in detached mode:

```shell
docker compose up -d
```

Refresh the page in your browser (`http://localhost:3000/`); the welcome page should appear again.

## Connecting an AI Agent

Click **Let’s get started**.

Complete the administrator account setup. For local deployments, you may use a simple password; for server deployments, choose a strong password. The email entered is only used as an identifier or login; no emails are sent to it.

Open WebUI supports two methods for connecting AI agents:

-   **Direct connection**: each user provides their own API key and URL.
-   **Global connection**: connection settings are configured once in the admin panel and used by all users.

### Direct Connection

After creating the admin account, you will be in the main workspace. To connect agents:

1.  Click the account name in the lower-left corner and select **Admin Panel**.
    
2.  Go to **Settings** → **Connections** and enable **Direct Connections**. Save changes.
    
3.  To connect a model, click the account name again and select **Settings** → **Connections**, then click the **+** icon.
    
4.  In the popup, enter:
    

-   **URL**: copy from the OpenAI URL field on the agent’s **Access** tab in the Hostman dashboard.
    
-   **Key**: [API token](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/) for accessing the agent.
    

6.  Click **Test Connection**. If there are no errors, save the configuration.
    
7.  Close the settings window and click **New Chat**. Your AI agent’s model should appear in the model selection menu. If not, refresh the page and check again.
    

At this point, Open WebUI installation and direct agent connection are complete.

### Global Connection (for all users)

To configure a single connection for all users:

1.  Click the account name in the lower-left corner and select **Admin Panel**.
    
2.  Go to **Settings** and click the **+** icon next to **OpenAI API**.
    
3.  In the popup, enter:
    

-   **URL**: from the agent’s **OpenAI URL** field in Hostman.
    
-   **Key**: [API token](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/) for agent access.
    

5.  Click **Test Connection**, then save if successful.
    
6.  Close the settings window and click **New Chat**. Your AI agent’s model should appear in the model selection menu. If not, refresh the page and check again.
    

Open WebUI is now fully set up and connected to your AI agent.

# AI Solutions

Source: https://hostman.com/docs/ai-agents/ai-solutions/

AI Solutions is a service for deploying ready-made AI agents. You choose a solution and a model, and the service automatically creates a cloud server and installs everything needed—no manual server or agent setup required.

Fully automatic deployment is currently available for **OpenClaw**: the agent starts right away, and you can work with it directly from the chat in the dashboard. You can also connect a Telegram bot for messenger access.

For **n8n** and **Hermes**, the service takes you to [Cloud Servers](https://hostman.com/my/servers) with a matching image already selected—you just complete the server order, and the required software installs automatically. Once that's done, you set up the agent on the server yourself.

The rest of this article covers the OpenClaw flow specifically.

## How the Deployment Works

-   Each solution deploys a cloud server with a fixed configuration that can't be changed.
-   The server's location is chosen at random.
-   SSH access and management from the control panel aren't available.
-   The server gets a public IP address.
-   The agent runs in a Docker container and has no direct access to the underlying cloud server.

## Pricing

An AI Solution's cost has three components:

-   **Cloud server and public IP**. Billed hourly at a fixed rate.
-   **AI Gateway key**. Costs $0.01 per month.
-   **Tokens**. Billed based on usage. Cost depends on the selected model and the number of input and output tokens consumed.

In [Active services](https://hostman.com/my/finances/services), an AI Solution appears as a single service with the combined cost of all three components.

## Create an AI Solution

To create an AI Solution:

1.  Go to **AI Services** → **AI Solutions** and click **OpenClaw**.
2.  Select the model the agent will use. You can change the model later.
3.  Enter a name for the agent and select a project. Add a comment if needed.
4.  Click **Install**.

Open the new solution under **AI Services** → **AI Solutions**. Once deployment finishes, you can send the agent a message from the **Chat** tab.

## Chat with the Agent

To start a conversation with the agent:

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  Open the **Chat** tab.
3.  Type a message describing the task and send it.

## Connect a Telegram Bot

You can connect a Telegram bot to chat with the agent through the messenger. Each AI Solution supports only one connected Telegram bot.

Before you start, create a bot with [BotFather](https://t.me/BotFather) on Telegram and save the API token it gives you.

To connect the bot:

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  On the **Integrations** tab, click **Connect**.
3.  Enter the bot's API token from BotFather and click **Add**.
4.  Open a chat with your bot in Telegram, using the account that needs access to the agent, and send any message. The bot replies with an integration code.
5.  Copy the code, enter it in the Hostman dashboard, and click **Confirm**.

Once the code is confirmed, only the Telegram user who received it can chat with the agent through the bot—no other users get access.

Send a message from the connected account to verify the integration works.

## Manage an AI Solution

The **Management** tab lets you change the model, reissue the AI Gateway key, and view token usage statistics.

### Change the Model

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  On the **Management** tab, click **Modify** next to **Configuration**.
3.  Select the model you want.
4.  Click **Save**.

### View Token Usage

To check token usage:

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  On the **Management** tab, click **Key dashboard** next to **AI Gateway key**.
3.  Check token usage statistics.

### Set Token Consumption Limit

To set up a token consumption limit:

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  On the **Management** tab, click **Key dashboard** next to **AI Gateway key**.
3.  Open the **Management** tab and click **Set limits**.
4.  To set **an overall limit**:
    -   Enable **Common consumption limit**.
    -   Enter the number of tokens (input + output) allowed per day.
5.  To set **a limit per model**:
    -   Enable **Per-model consumption limit**.
    -   Click **Select models**.
    -   Choose the models to limit.
    -   Enter the number of tokens (input + output) allowed per day for each.
6.  (Optional) Click **Add limit** to set another limit.
7.  Click **Save**.

### Reissue the AI Gateway Key

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  On the **Management** tab, click **Regenerate** next to **AI Gateway key**.
3.  Click **Regenerate** again to confirm.

The new key is applied to the solution automatically, you don't need to enter it manually anywhere.

### Pause and Resume a Solution

You can pause a solution at any time.

**To pause a solution:**

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  Click the pause icon in the top right.
3.  Click **Stop** to confirm.

> [!NOTE]
> Pausing a solution doesn't pause billing—the server continues to be charged at its regular rate.

**To resume a solution:**

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  Click the start icon in the top right.

### Delete a Solution

To delete a solution:

1.  Go to **AI Services** → **AI Solutions** and select the solution.
2.  Click the trash bin icon in the top right.
3.  Confirm the deletion.

# Integrating Coding Assistant

Source: https://hostman.com/docs/ai-agents/coding-assistants/

Hostman AI agents and AI Gateway work with the coding assistants you already use. Connect directly from your editor or terminal—no need to switch to a separate interface.

The guides below cover setup for the most popular tools:

-   [Cline](https://hostman.com/docs/ai-agents/coding-assistants/cline/)
-   [Codex](https://hostman.com/docs/ai-agents/coding-assistants/codex/)
-   [OpenCode](https://hostman.com/docs/ai-agents/coding-assistants/opencode/)
-   [Roo Code](https://hostman.com/docs/ai-agents/coding-assistants/connecting-to-vscode/)

# Cline

Source: https://hostman.com/docs/ai-agents/coding-assistants/cline/

Cline is a VS Code extension that lets you work with an AI model directly from your editor—ask questions about your project, edit code, and run terminal commands without switching context.

Cline can be used as an alternative to Roo Code, which is no longer supported.

## Installing Cline

1.  Open VS Code.
2.  Go to the **Extensions** panel.
3.  Search for **Cline** and install it.

![6f7a56e6 9a66 433d 817a 0eecf7a51515.png](https://content.hostman.com/assets/c3506be7-58e4-49c9-ba86-3d7d6f0b48ca.png?width=1999&height=1259)

_Cline page in the [VSCode](https://code.visualstudio.com/) interface_

Once installed, a **Cline** tab appears in the sidebar with a chat interface.

## Connection Requirements

You can connect either an AI agent or an AI Gateway to Cline.

To connect an AI agent, you'll need:

-   [The agent's base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url)
-   [An API key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

To connect AI Gateway, you'll need:

-   Base URL: `https://ai-api.hostman.com/v1`
-   [An API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key)

## Configuring the Connection

1.  Open the **Cline** tab.
    
2.  On first launch, you'll be prompted to choose an account type. Select **Bring my own API key** and click **Continue**.
    

![932b54a2 7593 4057 B680 55bf108120fd.png](https://content.hostman.com/assets/3eb65505-4081-4a93-9791-289c5cce7720.png?width=1999&height=1260)

_Cline setup in the [VSCode](https://code.visualstudio.com/) interface_

3.  Enter your provider settings:
    
    -   **API Provider**: OpenAI Compatible
        
    -   **Base URL**: your base URL
        
    -   **API Key**: your API key
        
    -   **Model**: if you're using an AI agent, you can leave this blank or enter the model name from your agent settings. For AI Gateway, specify the model name—for example, `openai/gpt-5-nano`. You can [find the correct model identifier](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) in the AI Gateway **Connection** tab.
        
4.  Optionally, configure generation parameters. These apply only when using an AI Gateway connection. Expand **Model configuration** and set:
    
    -   **Context Window Size**: the amount of conversation history included in each request
        
    -   **Max Output Tokens**: the maximum number of tokens in the model's response
        
    -   **Temperature**: controls how varied the model's responses are
        
5.  Click **Done**, then click the back arrow to return to the chat.
    

You can now send messages to your agent or model directly from the editor.

# Codex

Source: https://hostman.com/docs/ai-agents/coding-assistants/codex/

Codex is an AI coding assistant from OpenAI. It lets you work with your project directly from a desktop app or terminal—ask questions about your code, make changes, and run commands.

You can connect either an AI agent or an AI Gateway to Codex. With an AI agent, you work with a pre-configured agent setup; with AI Gateway, you call the model directly.

## Installing Codex

**Codex Desktop** is available for macOS and Windows. Download the installer for your OS from the [OpenAI website](https://openai.com/codex/get-started/).

**Codex CLI** can be installed on **macOS** or **Linux** with:

```shell
curl -fsSL https://chatgpt.com/codex/install.sh | sh
```

On **Windows**, use PowerShell:

```shell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```

You can also install Codex CLI via a package manager:

#### npm

```shell
npm install -g @openai/codex
```

#### Homebrew

```shell
brew install --cask codex
```

## Connection Requirements 

Before configuring Codex, decide which connection type you'll use.

To connect an AI agent, you'll need:

-   [The agent's base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url)
-   [An API key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

To connect AI Gateway, you'll need:

-   Base URL: `https://ai-api.hostman.com/v1`
-   [An API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key)

## Configuring the Connection

All configuration lives in `~/.codex/config.toml`.

If you've used Codex before and want to preserve your existing setup, back up the current config first:

```shell
mv ~/.codex/config.toml ~/.codex/config.toml_old
```

Rename it back at any time to restore your previous settings.

Open or create the config file:

```shell
nano ~/.codex/config.toml
```

Add the following:

```shell
model_provider = "hostman"
model = "openai/gpt-5-mini"

[model_providers.hostman]
name = "Hostman"

base_url = "https://ai-api.hostman.com/v1"
env_key = "HOSTMAN_API_KEY"
```

Adjust the values to match your setup:

-   `base_url`: Use `https://ai-api.hostman.com/v1` for AI Gateway, or your agent's base URL if connecting an AI agent.
    
-   `model`: For AI Gateway, specify the model name (e.g. `openai/gpt-5-nano`); for an AI agent, use the model name from your agent settings. Check the [AI Gateway**AI Gateway Connection tab** tab](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) for the correct identifier.
    
-   `env_key`: The name of the environment variable that will hold your API key.
    
-   `name`: Optional; change the provider display name if needed.
    

Codex reads the API key from the environment variable specified in `env_key`. If your config uses `HOSTMAN_API_KEY`, set it with:

#### Linux

```shell
export HOSTMAN_API_KEY="your-api-key"
```

#### macOS

```shell
launchctl setenv HOSTMAN_API_KEY "your-api-key"
```

#### Windows

```shell
setx HOSTMAN_API_KEY "your-api-key"
```

Then start Codex:

```shell
codex
```

If you're using the desktop app, restart it to apply the changes.

The model you configured will be available in both Codex CLI and the Codex desktop app—in the desktop version, it appears directly in the chat window.

# OpenCode

Source: https://hostman.com/docs/ai-agents/coding-assistants/opencode/

OpenCode is an AI coding assistant that lets you ask questions about your project, edit code, and run commands—all without leaving your current workflow.

You can connect either an AI agent or an AI Gateway to OpenCode. With an AI agent, you work with a pre-configured agent setup; with AI Gateway, you call the model directly.

## Installing OpenCode

OpenCode runs on Windows, Linux, and macOS, and is available as a TUI/CLI tool or a desktop app.

### Installing the TUI/CLI Version 

Use your preferred method:

#### curl

```shell
curl -fsSL https://opencode.ai/install | bash
```

#### npm

```shell
npm i -g opencode-ai
```

#### bun

```shell
bun add -g opencode-ai
```

#### Homebrew

```shell
brew install anomalyco/tap/opencode
```

#### paru

```shell
paru -S opencode
```

### Installing the Desktop App

Use Homebrew:

```shell
brew install --cask opencode-desktop
```

Alternatively, download the binary directly from the [OpenCode website](https://opencode.ai/download) and install it manually.

## Connection Requirements

You can connect either an AI agent or an AI Gateway to OpenCode.

To connect an AI agent, you'll need:

-   [The agent's base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url)
-   [An API key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

To connect AI Gateway, you'll need:

-   Base URL: `https://ai-api.hostman.com/v1`
-   [An API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key)

## Configuring the Connection

### TUI/CLI

Use this method if you're running the TUI/CLI version of OpenCode.

1.  Create or edit the `opencode.json` configuration file. You can place it in one of two locations:
    

-   Project root: settings apply to that project only
    
-   `~/.config/opencode/opencode.json`: settings apply globally across all projects
    

3.  Add the following configuration:
    

```shell
{
 "$schema": "https://opencode.ai/config.json",
 "provider": {
   "hostman": {
     "npm": "@ai-sdk/openai-compatible",
     "name": "Hostman",
     "options": {
       "baseURL": "https://ai-api.hostman.com/v1"
     },
     "models": {
       "openai/gpt-5-mini": {
         "name": "openai/gpt-5-mini"
       }
     }
   }
 },
 "model": "openai/gpt-5-mini"
}
```

Adjust the values to match your setup:

-   -   `baseURL`: if you're connecting an AI agent, replace this with your agent's base URL. For AI Gateway, leave it as-is.
        
    -   `models`: the list of models that will be available in OpenCode.
        
    -   `model`: for AI Gateway, specify the model name—for example, `openai/gpt-5-nano`. For an AI agent, use the model name from your agent settings. [Check the **Check the Connection tab** tab](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) for the correct identifier.
        
    -   `name`: optional; change the provider display name if needed.
        

3.  Save and close the file.
    
4.  Set your API key. Start OpenCode in the terminal:
    

```shell
opencode
```

5.  In the TUI, run:
    

```shell
/connect
```

6.  Scroll down through the provider list and select **Other**.
    
7.  Enter the provider ID. This must match the provider key in `opencode.json` —in this example, `hostman`.
    
8.  Paste your API key.
    

OpenCode saves the key to an encrypted global auth file.

You can now use OpenCode. If you exited the TUI, restart it, then select your model by running:

```shell
/model
```

Search for the provider name you set earlier, then verify the connection by sending a message in the chat.

### Desktop App

1.  Click the gear icon to open settings.
    
2.  Go to the **Providers** tab.
    
3.  Scroll down and select **Custom provider**.
    
4.  Click **Connect**.
    
5.  Fill in the connection details:
    

-   **Provider ID**: a unique identifier you'll use to find this provider later
    
-   **Display name**: how the provider appears in the interface
    
-   **Base URL**: your agent's base URL or the AI Gateway URL
    
-   **API key**: the key for your agent or AI Gateway
    
-   **Models**: the list of models available for selection
    

7.  For AI Gateway, model names must follow the AI Gateway format—for example, `openai/gpt-5-nano`. [Check the Connection tab](https://hostman.com/docs/ai-agents/ai-gateway/connection/#getting-connection-details) for the correct identifier. For an AI agent, you can use any name.
    
8.  Click **Submit** to save.
    

Find and select your model in the chat, then verify the connection by sending a test message.

# Roo Code

Source: https://hostman.com/docs/ai-agents/coding-assistants/connecting-to-vscode/

AI agents can be integrated with any tools that support the OpenAI API, including VS Code extensions. For example, using Roo Code, an agent can interact with the editor: access project files, edit code, and execute commands in the terminal.

> [!NOTE]
> As of May 15, 2026, Roo Code is no longer supported. As an alternative, you can [use Cline](https://hostman.com/docs/ai-agents/coding-assistants/cline/), an extension with similar functionality and interface.

## Installing Roo Code

1.  Open VS Code.
2.  Go to the **Extensions** section.
3.  Search for **Roo Code** and install the extension.

![581b3a15 5886 4dfc 8950 Cb7ab95ac052.png](https://content.hostman.com/assets/f0425c9a-6073-48f1-bce0-4fe5ce9b0318.png?width=2726&height=1626)

_Roo Code page in the "Extensions" section of the [VS Code](https://code.visualstudio.com/) interface_

After installation, a Roo Code tab will appear in the sidebar with the chat interface.

## Configuring Connection to an AI Agent

To configure the connection, you will need:

-   [The agent’s Base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url)
-   [Your API key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

Follow these steps:

1.  Go to the **Roo Code** tab.
    
2.  Click the **gear icon** to open settings.
    
3.  Navigate to the **Providers** section.
    
4.  In the provider settings, enter:
    

-   **API Provider**: `OpenAI Compatible`
    
-   **Base URL**: `<agent’s base URL>`
    
-   **API Key**: `<your API key>`
    
-   **Model**: `<model name from agent settings>`
    

6.  Disable **Enable streaming** if it is turned on.
    
7.  Optionally, configure generation parameters:
    

-   **Context Window Size**: the amount of dialogue history sent in each request
    
-   **Max Completion Tokens**: maximum number of tokens in the response
    

9.  Click **Save**, then the back arrow to return to the chat.
    

You can now send messages to the agent directly from VS Code.

## Setting Agent Behavior (Optional)

You can modify the agent’s behavior, for example, to make it respond in Portuguese:

1.  Open Roo Code **Settings**.
2.  Go to the **Prompts** section.
3.  Add the phrase: `Responda em português`.

The agent will now reply in Portuguese when you send messages from the editor.

# Agent and Knowledge Base Pricing

Source: https://hostman.com/docs/ai-agents/pricing/

AI agents use large language models and a knowledge base. This section describes the pricing models and how tokens are counted.

-   [How Tokens Work](https://hostman.com/docs/ai-agents/pricing/how-tokens-work/)
-   [Agent Billing](https://hostman.com/docs/ai-agents/pricing/billing-models/)
-   [Knowledge Base Billing](https://hostman.com/docs/ai-agents/pricing/knowledge-base-billing/)
-   [Token Usage Limit](https://hostman.com/docs/ai-agents/pricing/token-usage-limit/)
-   [Changing Agent Plan](https://hostman.com/docs/ai-agents/pricing/change-plan/)
-   [Purchasing Additional Tokens](https://hostman.com/docs/ai-agents/pricing/buy-tokens/)

# How Tokens Work

Source: https://hostman.com/docs/ai-agents/pricing/how-tokens-work/

Models process text by splitting it into smaller units called tokens. A token can be:

-   part of a word (for example, "techno" + "logy");
-   a short word;
-   a symbol or punctuation mark.

On average, 1,000 tokens ≈ 750 words.

These values are approximate and provided only to give a general idea of usage costs. Each model uses its own tokenizer and splits text differently.

Tokens are billed for both input and output. For example, if your request contains 20 tokens and the model generates a response of 30 tokens, a total of 50 tokens will be deducted from your quota.

# Agent Billing

Source: https://hostman.com/docs/ai-agents/pricing/billing-models/

AI agents use a pay-as-you-go pricing model. All newly created agents are billed using this model.

Package-based pricing is available only for a limited number of agents created shortly after the service launch.

## Pay-as-you-go Pricing

Agents are billed at $0.10 per month, while token usage is charged separately on a pay-as-you-go basis. Input and output tokens are billed independently at different rates.

Current pricing is available in the dashboard

Charges are deducted from your account balance once per hour. You can also [configure token usage limits](https://hostman.com/docs/ai-agents/pricing/token-usage-limit/) to control spending.

## Package-based Pricing

> [!NOTE]
> Creating new agents with package-based pricing is not possible.

With package-based pricing, an agent is assigned a monthly token package selected by you.

The subscription renews automatically once per month with a single charge, and the same token package becomes available again. Any unused tokens expire at the end of the billing period.

You can [upgrade your plan](https://hostman.com/docs/ai-agents/pricing/change-plan/) at any time, but downgrades are not available.

If your token limit is reached, you can either switch to a higher plan or [purchase an additional token package](https://hostman.com/docs/ai-agents/pricing/buy-tokens/) valid until the end of the current billing period (you can check the renewal date in **Billing** → **Billing history**).

# Knowledge Base Billing

Source: https://hostman.com/docs/ai-agents/pricing/knowledge-base-billing/

Knowledge base pricing includes token subscription fees and infrastructure costs for the underlying OpenSearch database. This article explains how charges are calculated, how tokens are consumed, and what affects the total cost.

## How Price Is Calculated

The cost of a knowledge base consists of two components:

-   **Token Subscription Fee**. When a knowledge base is created, $5.63 is charged for 10 million tokens. These tokens are used for indexing the knowledge base and for all queries to it. This charge repeats monthly.
    
-   **Hourly Fee for the OpenSearch Database**. The knowledge base runs on a cloud database. After the database is created, hourly billing starts. The cost depends on the selected configuration.
    

When creating the database, choose the smallest suitable configuration. You can increase it later if needed, but downgrading is not supported.

#### Pricing Example

When creating a knowledge base with the minimum configuration:

-   $5.63 is charged immediately for 10 million tokens (monthly charge).
-   $0.06831 per hour is charged for the database while it is running throughout the month.

## Additional Tokens

If needed, you can add tokens at a price of $0.75 per 1,000,000 tokens by clicking **Add Tokens** on the knowledge base **Dashboard**:

![Charming Smew 2026 08 19 13 51](https://content.hostman.com/assets/3feb5e3d-a779-46dc-80c9-dca479aa4a36.png?width=1583&height=836)

Additional tokens are valid only until the end of the current billing period. For example, if the next billing date is in two days, the added tokens will expire in two days.

## Token Usage During Indexing

Indexing uses the text-embedding-3-large embedding model, which converts text into vector representations. This is required for indexing data and enabling search and retrieval.

Token usage during indexing depends on the format of the uploaded file. Below is an approximate estimate of token consumption for documents of different sizes:

| **Format** | **1 MB** | **10 MB** | **100 MB** | **500 MB** |
| --- | --- | --- | --- | --- |
| **.txt** | 240,000 | 2,400,000 | 24,000,000 | 120,000,000 |
| **.csv** | 450,000 | 4,500,000 | 45,000,000 | 225,000,000 |
| **.xml** | 62,000 | 620,000 | 6,200,000 | 31,000,000 |
| **.htm**, **.html** | 39,000 | 390,000 | 3,900,000 | 19,500,000 |
| **.md** | 221,000 | 2,210,000 | 22,100,000 | 110,500,000 |

Actual token usage may vary depending on the structure and content of the file.

# Token Usage Limit

Source: https://hostman.com/docs/ai-agents/pricing/token-usage-limit/

You can configure token usage limits when creating an agent or later in the agent settings to help control token consumption and spending.

> [!NOTE]
> This feature is available only for agents using [pay-as-you-go pricing](https://hostman.com/docs/ai-agents/pricing/billing-models/#pay-as-you-go-pricing).

## During Agent Creation

On the **Pricing** step, specify the desired token usage limit. You can change this value at any time.

![Create AI Agent 2026 08 14 15 52](https://content.hostman.com/assets/ee741933-8f75-4b0b-8063-1149c7619647.png?width=748&height=608)

## In Agent Settings

1.  Open the required agent in the **AI Services** → **Agents** section.
2.  Go to the **Management** tab and click **Set limits**.

![Inventive Umbriel 2026 08 14 15 53](https://content.hostman.com/assets/43928e01-0235-4bdc-a1c7-b0ab9a21c90b.png?width=1570&height=868)

3.  Enable or disable the limit and specify the required value.
4.  Save the changes.

![Inventive Umbriel 2026 08 14 15 54](https://content.hostman.com/assets/9b58797f-d622-48d6-b7d0-8c0df3d082b5.png?width=1744&height=869)

# Change Agent Plan

Source: https://hostman.com/docs/ai-agents/pricing/change-plan/

You can upgrade the plan of an existing agent using the instructions below, or [purchase an additional token package](https://hostman.com/docs/ai-agents/pricing/buy-tokens/) for the current month without changing the plan.

> [!NOTE]
> This feature is available only for agents using [package-based pricing](https://hostman.com/docs/ai-agents/pricing/billing-models/#package-based-pricing).

**Important:** When you change the plan, any unused tokens will be lost. After the change, only the number of tokens included in the new plan will be available.

To change the plan:

1.  Go to **AI Services** → **Agents** and click on the agent.
2.  On the **Management** tab, click **Modify** next to the current configuration.

![C7962551 6321 4c17 9175 Cfef60a6e776](https://content.hostman.com/assets/f30f36de-d6dd-4682-9289-dfa22fcba911.png?width=1569&height=1090)

3.  Select a new plan and save the changes.

The changes take effect immediately, and the token counter is updated right away.

# Purchase Additional Tokens

Source: https://hostman.com/docs/ai-agents/pricing/buy-tokens/

If your agent needs more tokens, you can either [upgrade the plan](https://hostman.com/docs/ai-agents/pricing/change-plan/) or purchase additional tokens separately.

> [!NOTE]
> This feature is available only for agents using [package-based pricing](https://hostman.com/docs/ai-agents/pricing/billing-models/#package-based-pricing).

-   Use a plan upgrade if you need a higher token limit on an ongoing basis, as downgrading the plan is not supported.
-   If you only need extra tokens temporarily, purchase an additional token package. It will remain valid only until the end of the current billing period. After that, you will continue paying for your standard plan.

To purchase a token package:

1.  Go to **AI Services** → **Agents** and click on the agent.
2.  On the **Dashboard** tab, click **Add tokens**.

![9c4e1168 B6cb 45fb Aff5 3f5cbe87210d](https://content.hostman.com/assets/a282b838-6109-44b9-b909-8680e194b8dc.png?width=1559&height=1018)

3.  Specify the number of tokens you want (in increments of 250,000) and click **Confirm**.

![7a749dab Fce2 42eb Af63 Ad1087c5c343](https://content.hostman.com/assets/6e5b6aaa-ce21-4382-88a0-e6be3eb86465.png?width=1555&height=824)

# Cloud Databases

Source: https://hostman.com/docs/dbaas/

[Cloud database](https://hostman.com/managed-database/), or Database as a Service (DBaaS), is a cloud-based solution for storing and managing structured data. DBaaS provides a fully automated, flexible and scalable database platform.

When using cloud databases, you do not need to install and maintain hardware, configure software, or administer complex storage facilities. 

To start working with the database, simply create the service in your Hostman dashboard, and a database cluster will be created for you from cloud resources with the specified parameters. 

You can work with the database as usual: connect to it, add, edit and delete data, and so on.

A database cluster is one or several virtual machines on which database servers are deployed. If there are several virtual machines, one of them is the master server, and the rest are replicas in exactly the same configuration, which provide fault tolerance.

> [!NOTE]
> At the moment, we provide database clusters consisting of one server of the selected configuration. Within a cluster, you can create multiple databases and users for them.

DBaaS benefits:

-   Fast processing of requests of any complexity.
    
-   Easy scaling.
    
-   Reducing infrastructure maintenance costs.
    
-   Productivity and security.
    

With [DBaaS](https://hostman.com/dbaas/), you can save time, reduce costs, and simplify database management.

# Create Database Clusters

Source: https://hostman.com/docs/dbaas/create-database/

You can create managed database clusters consisting of one or more databases.

To create a new cluster:

1.  Go to the **[Databases](https://hostman.com/my/database)** section and click **Create Database**.
2.  Select the database type and its version: MySQL, PostgreSQL, Valkey etc. Once created, you won’t be able to change the database type or version.
3.  Select the region where your database cluster should be located.
    
4.  Select the plan, i.e. the configuration of your cluster. 
    

On the basic plan, MySQL and PostgreSQL clusters are limited to a single database and a single user, and some configuration parameters cannot be modified. For details, see the [MySQL](https://hostman.com/docs/dbaas/mysql/#basic-plan-limitations) and [PostgreSQL](https://hostman.com/docs/dbaas/postgresql/#basic-plan-limitations) limitations.

5.  Select the network settings. You can either create a new private network or add this cluster to an existing one. You can also manually assign a private IP address for this database cluster.
    

When creating a new network, you’ll need to set the IP address range for it. 

| **Available ranges** | **Maximum CIDR size** | **Minimum CIDR size** |
| --- | --- | --- |
| 10.0.0.0/x | /8 | /28 |
| 192.168.0.0/x | /16 | /28 |
| 172.16.0.0/x | /12 | /28 |

6.  Enable the backups if necessary. If enabled, one backup copy will be created daily. You can always enable or disable this option later.
7.  Set the password for the default database user. After the cluster is created, you can add other database users as well as change the password of the default one. 
8.  You can also set your custom name for the cluster, add a comment and choose the project to add the cluster to.
9.  Click **Create** and you can start working with the database in a couple of minutes.

The database will be issued a public IP address, which you can see in the dashboard. If necessary, you can disable access via public IP in the database settings.

# MySQL Management

Source: https://hostman.com/docs/dbaas/mysql/

MySQL is a database management system used for storing and processing structured data. In a DBaaS environment, you get a managed database cluster without the need for manual configuration: everything is handled automatically.

When [creating a cluster](https://hostman.com/docs/dbaas/create-database/), you can choose the MySQL version: 8.0 or 8.4.

## Creating Databases

When you create a new cluster, a database named `default_db` is created automatically. 

You can create additional databases:

1.  Go to the **Databases** section of your Hostman dashboard.
    
2.  Click on the cluster.
    
3.  In the **Databases** tab, click **Add**.
    

![D0a5a312 9792 48b9 9260 5367c8ea1aa9](https://content.hostman.com/assets/774bb10d-62f8-41c2-bbe5-af65f27af621.png?width=1530&height=753)

4.  Provide a name for your database: 3–64 characters. Letters, numbers, and special characters are allowed.
    
5.  Add a description, if necessary.
    
6.  Click **Create**.
    

![Ab9a9e55 A570 4695 B4a6 A4d0e8601b2f](https://content.hostman.com/assets/1c797f9f-c75b-4530-a776-c25ebd3a6b55.png?width=1545&height=746)

## Database Import

To import a database:

1.  Go to the **Databases** section of your Hostman dashboard.
2.  Click on the cluster.
3.  In the **Databases** tab, click **Import**.
4.  Enter the connection details for the database you want to import.
5.  Click **Start import**. 

### Requirements and Limitations

-   **Network Access**: The source database must be accessible for connection from the internet from any IP address. Without this, the import will not start.
-   **Public IP**: The target cluster must have a public IPv4 address.
-   **Unique Name**: The target cluster must not contain a database with the same (identical) name.

**What will be transferred:**

-   Table structures
-   Data in tables

**What will not be transferred:**

-   Users

You will need to create users manually in the new database, after the import.

Before running the import, we recommend temporarily reducing the `innodb_buffer_pool_size` parameter to 50% of the RAM allocated to the database.

## Users and Privileges

In your Hostman dashboard, you can manage MySQL users and their privileges.

### Creating Users

When a new cluster is provisioned, it automatically includes a database user named `gen_user`. You can add more users in the **Users** tab of the interface.

1.  Go to the **Databases** section and click on the cluster.
    
2.  Open the **Users** tab and click **Add**.
    

![E4d188f2 84e5 435b 96d8 6e6dcd7279cb](https://content.hostman.com/assets/09a81a3d-521d-4633-bac3-02d16689ff9f.png?width=1510&height=686)

3.  Set the username and password:
    

-   Username: 3–32 characters. Letters, numbers, and special characters are allowed.
    
-   Password: 8–30 characters. Letters, numbers, and special characters are allowed.
    

5.  (Optional) Configure the user’s privileges. You can also leave the default parameters and change them later at any time.
    
6.  Click **Create**.
    

### Modifying Privileges

To update the privileges of an existing user:

1.  Go to the **Databases** section and click on the cluster.
    
2.  Open the **Users** tab.
    
3.  Click the three dots next to the user.
    
4.  Select **Privileges**.
    

![0c28ea74 F1df 4911 Aa39 96ba34885a90](https://content.hostman.com/assets/55925810-3f1c-4569-8f83-eed24648ee21.png?width=1531&height=800)

5.  Choose the required privileges. You can grant access to a specific database or grant the same privileges for all databases by enabling **Identical for all databases** in the top right.
    

![9218d1cb 04a7 47e6 Ba18 28fc05918779](https://content.hostman.com/assets/39b1d813-78b8-400b-bf90-c10e88edbe6b.png?width=1528&height=1276)

### Available Privileges

| **Privilege** | **Description** |
| --- | --- |
| `USAGE` | Basic privilege that allows login without access to objects. |
| `SELECT` | Read data from tables and views. |
| `INSERT` | Add new records. |
| `UPDATE` | Modify existing records. |
| `DELETE` | Remove records. |
| `CREATE` | Create new tables, indexes, and other objects. |
| `DROP` | Remove objects such as tables or databases. |
| `REFERENCES` | Use foreign keys. |
| `INDEX` | Create and drop indexes. |
| `ALTER` | Modify the structure of existing tables. |
| `LOCK TABLES` | Use manual table locking. |
| `CREATE VIEW` | Create views. |
| `SHOW VIEW` | Display the structure of existing views. |
| `CREATE ROUTINE` | Create stored procedures and functions. |
| `ALTER ROUTINE` | Modify stored procedures and functions. |
| `EVENT` | Create and manage events (`EVENT SCHEDULER`). |
| `TRIGGER` | Create and drop triggers. |
| `SELECT` on `slow_log` | Read access to the system slow query log table. |
| `DROP` on `slow_log` | Ability to clear the contents of the `slow_log` table. |

### Changing User Password

You can change the user password:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Users** tab.
3.  Click the three dots next to the user.
4.  Select **Change password**.
5.  Enter a new value and save changes.

## Database Parameters

You can change database settings to optimize its performance. 

By default, the database is created with the parameters that are suitable for most tasks and will ensure the performance of the selected configuration. However, if your project requires specific settings, you can change them as you wish. 

Be careful and change parameters only if you are sure of their purpose. Incorrect configuration can negatively affect the operation of the database and its performance.

Available parameters depend on the MySQL version.

### MySQL 8.0 Parameters List

| **Parameter** | **Valid Values** | **Default Value** |
| --- | --- | --- |
| [auto\_increment\_increment](https://dev.mysql.com/doc/refman/8.0/en/replication-options-source.html#sysvar_auto_increment_increment) | 1–65535 | 1 |
| [auto\_increment\_offset](https://dev.mysql.com/doc/refman/8.0/en/replication-options-source.html#sysvar_auto_increment_offset) | 1–65535 | 1 |
| [innodb\_io\_capacity](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_io_capacity) | 100–4294967295 | 1500 |
| [innodb\_purge\_threads](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_purge_threads) | 1–32 | 4 |
| [innodb\_read\_io\_threads](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_read_io_threads) | 1–64 | 4 |
| [innodb\_thread\_concurrency](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_thread_concurrency) | 0–1000 | 0 |
| [innodb\_write\_io\_threads](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_write_io_threads) | 1–64 | 4 |
| [innodb\_log\_file\_size](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_log_file_size) | 4194304–274877906944 | 214748365 |
| [join\_buffer\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_join_buffer_size) | 128–18446744073709551488 | 67108864 |
| [max\_allowed\_packet](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet) | 1024–1073741824 | 16777216 |
| [max\_heap\_table\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_heap_table_size) | 16384–18446744073709550592 | 16777216 |
| [max\_connections](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections) | 1–100000 | 49 |
| [sql\_mode](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_sql_mode) | See [documentation](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_sql_mode) | — |
| [sort\_buffer\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_sort_buffer_size) | 32768–18446744073709551615 | 14680064 |
| [thread\_cache\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_thread_cache_size) | 0–16384 | 128 |
| [innodb\_flush\_log\_at\_trx\_commit](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit) | 0–2 | 1 |
| [transaction\_isolation](https://dev.mysql.com/doc/refman/8.3/en/server-system-variables.html#sysvar_transaction_isolation) | — | read-uncommitted |
| [long\_query\_time](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_long_query_time) | 0–31536000 | 10 |
| [tmp\_table\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_tmp_table_size) | 1024–18446744073709551615 | 16777216 |
| [table\_open\_cache](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_table_open_cache) | 1–524288 | 4970 |
| [table\_open\_cache\_instances](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_table_open_cache_instances) | 1–64 | 16 |
| [innodb\_flush\_method](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_method) | — | O\_DSYNC |
| [innodb\_strict\_mode](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_strict_mode) | On/Off | On |
| [slow\_query\_log](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_slow_query_log) | On/Off | On |
| [binlog\_cache\_size](https://dev.mysql.com/doc/refman/8.4/en/replication-options-binary-log.html#sysvar_binlog_cache_size) | 4096–18446744073709547520 | 32768 |
| [binlog\_group\_commit\_sync\_delay](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_group_commit_sync_delay) | 1–1000000 | 1 |
| [binlog\_row\_image](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_row_image) | — | full |
| [binlog\_rows\_query\_log\_events](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_rows_query_log_events) | On/Off | Off |
| [character\_set\_server](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_character_set_server) | — | utf8 |
| [explicit\_defaults\_for\_timestamp](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_explicit_defaults_for_timestamp) | On/Off | On |
| [group\_concat\_max\_len](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_group_concat_max_len) | 4–18446744073709551615 | 1024 |
| [innodb\_adaptive\_hash\_index](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_adaptive_hash_index) | On/Off | On |
| [innodb\_lock\_wait\_timeout](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_lock_wait_timeout) | 1–1073741824 | 50 |
| [innodb\_numa\_interleave](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_numa_interleave) | On/Off | Off |
| [net\_read\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_net_read_timeout) | 1–31536000 | 30 |
| [net\_write\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_net_write_timeout) | 1–31536000 | 1 |
| [regexp\_time\_limit](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_regexp_time_limit) | 0–2147483647 | 32 |
| [sync\_binlog](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_sync_binlog) | 0–4294967295 | 1 |
| [table\_definition\_cache](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_table_definition_cache) | 400–524288 | 2000 |
| [log\_bin\_trust\_function\_creators](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_log_bin_trust_function_creators) | On/Off | On |
| [skip\_name\_resolve](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_skip_name_resolve) | On/Off | Off |
| [innodb\_buffer\_pool\_size](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_buffer_pool_size) | 5242880–18446744073709551615 | 858993459 |
| [wait\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_wait_timeout) | 1–31536000 | 28800 |
| [interactive\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_interactive_timeout) | 1–31536000 | 28800 |
| [default-time-zone](https://dev.mysql.com/doc/refman/8.3/en/server-system-variables.html#sysvar_time_zone) | \-13:59–+14:00 | — |

### MySQL 8.4 Parameters List

| **Parameter** | **Valid Values** | **Default Value** |
| --- | --- | --- |
| [auto\_increment\_increment](https://dev.mysql.com/doc/refman/8.0/en/replication-options-source.html#sysvar_auto_increment_increment) | 1–65535 | 1 |
| [auto\_increment\_offset](https://dev.mysql.com/doc/refman/8.0/en/replication-options-source.html#sysvar_auto_increment_offset) | 1–65535 | 1 |
| [innodb\_io\_capacity](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_io_capacity) | 100–4294967295 | 1500 |
| [innodb\_purge\_threads](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_purge_threads) | 1–32 | 4 |
| [innodb\_read\_io\_threads](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_read_io_threads) | 1–64 | 4 |
| [innodb\_thread\_concurrency](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_thread_concurrency) | 0–1000 | 0 |
| [innodb\_write\_io\_threads](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_write_io_threads) | 1–64 | 4 |
| [innodb\_log\_file\_size](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_log_file_size) | 4194304–274877906944 | 214748365 |
| [join\_buffer\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_join_buffer_size) | 128–18446744073709551488 | 67108864 |
| [max\_allowed\_packet](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet) | 1024–1073741824 | 16777216 |
| [max\_heap\_table\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_heap_table_size) | 16384–18446744073709550592 | 16777216 |
| [max\_connections](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_connections) | 1–100000 | 49 |
| [sql\_mode](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_sql_mode) | See [documentation](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_sql_mode) | — |
| [sort\_buffer\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_sort_buffer_size) | 32768–18446744073709551615 | 14680064 |
| [thread\_cache\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_thread_cache_size) | 0–16384 | 128 |
| [innodb\_flush\_log\_at\_trx\_commit](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_log_at_trx_commit) | 0–2 | 1 |
| [transaction\_isolation](https://dev.mysql.com/doc/refman/8.3/en/server-system-variables.html#sysvar_transaction_isolation) | — | read-uncommitted |
| [long\_query\_time](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_long_query_time) | 0–31536000 | 10 |
| [tmp\_table\_size](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_tmp_table_size) | 1024–18446744073709551615 | 16777216 |
| [table\_open\_cache](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_table_open_cache) | 1–524288 | 4970 |
| [table\_open\_cache\_instances](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_table_open_cache_instances) | 1–64 | 16 |
| [innodb\_flush\_method](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_flush_method) | — | O\_DSYNC |
| [innodb\_strict\_mode](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_strict_mode) | On/Off | On |
| [slow\_query\_log](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_slow_query_log) | On/Off | On |
| [binlog\_cache\_size](https://dev.mysql.com/doc/refman/8.4/en/replication-options-binary-log.html#sysvar_binlog_cache_size) | 4096–18446744073709547520 | 32768 |
| [binlog\_group\_commit\_sync\_delay](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_group_commit_sync_delay) | 1–1000000 | 1 |
| [binlog\_row\_image](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_row_image) | — | full |
| [binlog\_rows\_query\_log\_events](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_binlog_rows_query_log_events) | On/Off | Off |
| [character\_set\_server](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_character_set_server) | — | utf8 |
| [explicit\_defaults\_for\_timestamp](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_explicit_defaults_for_timestamp) | On/Off | On |
| [group\_concat\_max\_len](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_group_concat_max_len) | 4–18446744073709551615 | 1024 |
| [innodb\_adaptive\_hash\_index](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_adaptive_hash_index) | On/Off | On |
| [innodb\_lock\_wait\_timeout](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_lock_wait_timeout) | 1–1073741824 | 50 |
| [innodb\_numa\_interleave](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_numa_interleave) | On/Off | Off |
| [net\_read\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_net_read_timeout) | 1–31536000 | 30 |
| [net\_write\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_net_write_timeout) | 1–31536000 | 1 |
| [regexp\_time\_limit](https://dev.mysql.com/doc/refman/8.4/en/server-system-variables.html#sysvar_regexp_time_limit) | 0–2147483647 | 32 |
| [sync\_binlog](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_sync_binlog) | 0–4294967295 | 1 |
| [table\_definition\_cache](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_table_definition_cache) | 400–524288 | 2000 |
| [log\_bin\_trust\_function\_creators](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#sysvar_log_bin_trust_function_creators) | On/Off | On |
| [skip\_name\_resolve](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_skip_name_resolve) | On/Off | Off |
| [innodb\_redo\_log\_capacity](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_redo_log_capacity) | 8388608–137438953472 | 104857600 |
| [innodb\_buffer\_pool\_size](https://dev.mysql.com/doc/refman/8.0/en/innodb-parameters.html#sysvar_innodb_buffer_pool_size) | 5242880–18446744073709551615 | 858993459 |
| [wait\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_wait_timeout) | 1–31536000 | 28800 |
| [interactive\_timeout](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_interactive_timeout) | 1–31536000 | 28800 |
| [default-time-zone](https://dev.mysql.com/doc/refman/8.3/en/server-system-variables.html#sysvar_time_zone) | \-13:59–+14:00 | — |

### Changing Parameters

1.  Go to the **Databases** section and click on the cluster.
    
2.  Go to the **Configuration** tab.
    
3.  Click **Modify parameters** next to **Database parameters**.
    

![7b1d4299 2822 4464 Aed0 01c008b5f271](https://content.hostman.com/assets/41518f45-ed84-477a-bd2f-37430e21d885.png?width=1534&height=970)

4.  Adjust the parameters. To read more about each parameter, click **Open description** next to it.
    

![Db5f0428 Be06 4ca6 8b32 E8599e6b863c](https://content.hostman.com/assets/0f04e744-d07a-41fd-b6a3-e7bf96855af1.png?width=1542&height=1133)

5.  Click **Apply and Restart** at the bottom of the page.
    
6.  Confirm the action.

### Resetting Parameters

If needed, you can restore one or all parameters to their default values.

> [!NOTE]
> Be careful: the parameters will be reset immediately, without additional confirmation.

#### Resetting a Single Parameter

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Reset to default** next to the parameter you want to reset. 
5.  Click **Apply and Restart** at the bottom of the page.
6.  Confirm the action.

#### Resetting All Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Restore default settings** at the bottom of the page.
5.  Click **Continue** to confirm. The cluster will be restarted.

### Importing and Exporting Parameters

MySQL parameters can be exported to a file and imported into another cluster.

#### Importing Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Import / export** → **Import parameters**.
5.  Select a JSON file containing the parameters.
6.  Click **Apply**.

The parameters file must contain an object with parameter names as keys and their values as strings:

```shell
{
  "parameter_name_1": "parameter_value_1",
  "parameter_name_2": "parameter_value_2"
}
```

If a parameter doesn't exist in the MySQL version you're using, or can't be modified, it will be ignored during import.

#### Exporting Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Import / export** → **Export parameters**.

Your browser will download a JSON file containing the current parameter values.

## Connecting to the Database

You can connect to your databases using a web interface or a terminal. Connecting via a web interface is possible only if the cluster has a public IP address.

### Adminer and phpMyAdmin

You can connect to the database via the built-in web interfaces: **Adminer** or **phpMyAdmin**.

1.  Go to the **Databases** section and click on the cluster.
    
2.  Click the **Web Interface** button and select the preferred option.
    

![8c3ebf75 7bdf 4bde A390 F3d01b0ead9b](https://content.hostman.com/assets/74f73dd5-7864-431e-8cca-a24ae3d1441f.png?width=1538&height=758)

### Terminal

Install the MySQL client:

-   Ubuntu:

```shell
sudo apt install mysql-client
```

-   Debian:

```shell
sudo apt install mariadb-client
```

-   Arch:

```shell
sudo pacman -S percona-server-clients
```

-   Fedora:

```shell
sudo dnf install mysql
```

There are two ways to connect to a MySQL cluster:

-   via public IP;
-   via private IP.

You can copy the connection command from:

-   the **Dashboard** tab;
    

![7a9bedf7 E231 41de 9fa8 3ff8f207c71e](https://content.hostman.com/assets/070fbd4d-8aa3-45c4-96bf-19c141d339bb.png?width=1542&height=1494)

-   the **Connection** tab.
    

![9a990da6 D164 4d38 A3d2 326cc2408ca4](https://content.hostman.com/assets/1aed9c0d-e549-48fe-8707-2c6adda44641.png?width=1552&height=758)

> [!NOTE]
> If you are using MariaDB 10.10 or higher as the client, use the option `--skip_ssl` when connecting to the cluster.

## Creating a Dump

To create a dump, run the following command:

```shell
mysqldump --set-gtid-purged=off -y -u gen_user -p'password' -h ip_dbaas default_db | gzip > default_db.sql.gz
```

Here:

-   `--set-gtid-purged=off` excludes the `SET @@GLOBAL.GTID_PURGED` command, which may cause errors if privileges are insufficient.
    
-   `-y (--no-tablespaces)` excludes tablespaces, preventing possible errors during dump creation.
    

## Importing a Dump

To import a dump, run:

```shell
cat default_db.sql.gz | gzip -d | mysql -u gen_user -p'password' -h ip_dbaas default_db
```

This command decompresses the dump and pipes it into the MySQL client for execution.

## Basic Plan Limitations

The basic database plan (1 CPU / 1 GB RAM / 20 GB NVMe) has the following technical limitations:

-   Additional databases cannot be added
-   Additional users cannot be added
-   The following parameters cannot be configured:
    -   `innodb_buffer_pool_size`
    -   `sort_buffer_size`
    -   `max_connections`
    -   `join_buffer_size`
    -   `thread_cache_size`

# PostgreSQL Management

Source: https://hostman.com/docs/dbaas/postgresql/

PostgreSQL is an open-source object-relational database management system. It is known for its reliability, scalability, and extensive functionality, including JSON support, full-text search, stored procedures, extensions, and more.

With Hostman managed PostgreSQL databases, you get a fully managed PostgreSQL cluster without manual setup: everything is handled automatically.

When creating a cluster, you can select the PostgreSQL version: 14, 15, 16, 17, 18.

## Creating Databases

When you create a new cluster, a database named `default_db` is created automatically. 

You can create additional databases:

1.  Go to the **Databases** section of your Hostman dashboard.
    
2.  Click on the cluster.
    
3.  In the **Databases** tab, click **Add**.
    

![C07452c6 6988 49f2 Bc35 Aa3bb634a399](https://content.hostman.com/assets/31aa8b5c-0a7f-4cdd-8e53-b2be6a379515.png?width=1537&height=753)

4.  Provide a name for your database: 3–64 characters. Letters, numbers, and special characters are allowed.
    
5.  Add a description, if necessary.
    
6.  Click **Create**.
    

![Ab9a9e55 A570 4695 B4a6 A4d0e8601b2f](https://content.hostman.com/assets/33181a05-f4ba-4f86-b004-246d5de70d95.png?width=1545&height=746)

## Database Import

To import a database:

1.  Go to the **Databases** section of your Hostman dashboard.
2.  Click on the cluster.
3.  In the **Databases** tab, click **Import**.

![Import](https://content.hostman.com/assets/e6faf2d1-3ec0-4177-8ef5-b09411e4045c.png?width=1540&height=755)

4.  Enter the connection details for the database you want to import.
5.  Click **Start import**. 

### Requirements and Limitations

-   **Network Access**: The source database must be accessible for connection from the internet from any IP address. Without this, the import will not start.
-   **Public IP**: The target cluster must have a public IPv4 address.
-   **Unique Name**: The target cluster must not contain a database with the same (identical) name.
-   **Version Compatibility**: Import supports transferring data between different versions of PostgreSQL (for example, from 17 to 18). However, some extensions and parameters may be incompatible or differ between versions.

**What will be transferred:**

-   Table structures
-   Indexes
-   Data in tables

**What will not be transferred:**

-   Users and roles
-   Extensions

You will need to create users and install the required extensions manually in the new database.

## Users and Privileges

When a new cluster is provisioned, it automatically includes a database user named `gen_user`. You can add more users in the **Databases** section.

### Creating Users

1.  Go to the **Databases** section and click on the cluster.
    
2.  Open the **Users** tab and click **Add**.
    

![Ee04ecdb 2a74 4a55 8e18 A7f2903c04de](https://content.hostman.com/assets/8497d3e2-3c02-43e6-8fca-0bd992c02a4e.png?width=1538&height=759)

3.  Set the username and password:
    

-   Username: 3–64 characters. Letters, numbers, and special characters are allowed.
    
-   Password: 8–30 characters. Letters, numbers, and special characters are allowed.
    

5.  (Optional) Configure the user’s privileges. You can also leave the default parameters and change them later at any time.
    
6.  Click **Create**.
    

### Modifying Privileges

To update the privileges of an existing user:

1.  Go to the **Databases** section and click on the cluster.
    
2.  Open the **Users** tab.
    
3.  Click the three dots next to the user.
    
4.  Select **Privileges**.
    

![26a04155 88de 43fd 8c8a E715a4e9d7b0](https://content.hostman.com/assets/dcdd4700-572d-4acc-94b3-3bbf530d91fe.png?width=1543&height=839)

5.  Choose the required privileges. You can grant access to a specific database or grant the same privileges for all databases by enabling **Identical for all databases** in the top right.
    

![6eae3e45 839c 4848 9e8b Be016c8df921](https://content.hostman.com/assets/d053f4f6-bdc1-4375-ad34-e2554090f556.png?width=1552&height=1208)

### Available Privileges

| **Privilege** | **Description** |
| --- | --- |
| `SELECT` | Read data from tables, views, and sequences. |
| `INSERT` | Add new rows into tables. |
| `UPDATE` | Modify existing rows in tables. |
| `DELETE` | Delete rows from tables. |
| `TRUNCATE` | Quickly delete all rows in a table (without logging each row deletion). |
| `CREATE` | Create new objects (tables, views, functions, etc.). |
| `REFERENCES` | Use a table as a foreign key. |
| `TRIGGER` | Create and execute triggers on a table. |
| `TEMPORARY` | Create temporary tables. |
| `CREATEDB` | Create new databases. |
| `CREATE_ROLE` | Create new roles. |

### Changing User Password

You can change the user password:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Users** tab.
3.  Click the three dots next to the user.
4.  Select **Change password**.
5.  Enter a new value and save changes.

## Extensions

PostgreSQL extensions allow you to expand the functionality of [PostgreSQL databases](https://hostman.com/postgresql/) by adding additional capabilities to solve certain tasks. You can read more about extensions in the PostgreSQL documentation.

### Enabling Extensions

To enable or disable extensions:

1.  Go to the **Databases** section and click on the cluster.
    
2.  Go to the **Configuration** tab.
    
3.  Click **Modify** next to **Extensions**.
    

![E5f9e2f3 B9fc 4d53 A4f5 B50f1e751b0d](https://content.hostman.com/assets/47f3dcb2-734b-43de-9796-a6a16b949d5b.png?width=1537&height=972)

4.  Select the database and the required extensions. To apply the same extensions to all databases in the cluster, enable the **Use the same extensions for all databases** option.
    

![C6debd31 Dcea 4e79 B5bb 5bbfc83252dc](https://content.hostman.com/assets/f7877dc2-9272-4ea1-aaf8-865198663eb0.png?width=1522&height=1106)

### Extensions List

The following extensions are available:

| **Extension** | **Description** |
| --- | --- |
| `amcheck` | Index and table integrity checking. |
| `citext` | Case-insensitive string type. |
| `cube` | Multidimensional point and cube data types, with distance calculations between them. |
| `earthdistance` | Calculates distances between geographic coordinates on Earth's surface. Requires the `cube` extension. |
| `fuzzystrmatch` | Fuzzy string matching for typo-tolerant search, using algorithms like Levenshtein and Soundex. |
| `hstore` | Stores key-value pairs in a single field. |
| `intarray` | Additional functions and operators for working with integer arrays. |
| `ltree` | Stores and queries hierarchical, tree-like data such as categories. |
| `pg_prewarm` | Preloads tables and indexes into cache to avoid cold starts after a restart. |
| `pg_stat_kcache` | Collects statistics on operating system resource usage. |
| `pg_stat_statements` | Collects and analyzes SQL query execution statistics. |
| `pg_trgm` | String search and comparison using trigrams (fuzzy search). |
| `pgagent` | Job scheduling agent |
| `pgcrypto` | Cryptographic functions: hashing, encryption, digital signatures. |
| `pgvector` | Vector data type with ivfflat and hnsw indexes for similarity search. |
| `postgis` | Work with geographic and geometric data (GIS). |
| `postgis_topology` | Topological models for spatial data. |
| `postgres_fdw` | Connects to and queries tables on remote PostgreSQL servers as if they were local. |
| `timescaledb` | Stores and processes time-series data, with support for scalable inserts and complex queries. |
| `unaccent` | Removes accents from text for accent-insensitive search. |
| `uuid-ossp` | Generate UUIDs of various versions. |

## Database Parameters

You can change database settings to optimize its performance. 

By default, the database is created with the parameters that are suitable for most tasks and will ensure the performance of the selected configuration. However, if your project requires specific settings, you can change them as you wish. 

Be careful and change parameters only if you are sure of their purpose. Incorrect configuration can negatively affect the operation of the database and its performance.

### Parameters List

| **Parameter** | **Values** | **Default** |
| --- | --- | --- |
| [autovacuum\_analyze\_scale\_factor](https://postgresqlco.nf/doc/en/param/autovacuum_analyze_scale_factor) | 0–100 | 0.1 |
| [autovacuum\_max\_workers](https://postgresqlco.nf/doc/en/param/autovacuum_max_workers/) | 1–262143 | 3 |
| [autovacuum\_naptime](https://postgresqlco.nf/doc/en/param/autovacuum_naptime/) | 1–2147483 | 60 |
| [autovacuum\_vacuum\_insert\_scale\_factor](https://postgresqlco.nf/doc/en/param/autovacuum_vacuum_insert_scale_factor/) | 0–100 | 0.2 |
| [autovacuum\_vacuum\_scale\_factor](https://postgresqlco.nf/doc/en/param/autovacuum_vacuum_scale_factor/) | 0–100 | 0.2 |
| [autovacuum\_work\_mem](https://postgresqlco.nf/doc/en/param/autovacuum_work_mem/) | \-1–2147483647 | \-1 |
| [bgwriter\_delay](https://postgresqlco.nf/doc/en/param/bgwriter_delay/) | 10–10000 | 200 |
| [bgwriter\_lru\_maxpages](https://postgresqlco.nf/doc/en/param/bgwriter_lru_maxpages/) | 0–1073741823 | 100 |
| [deadlock\_timeout](https://postgresqlco.nf/doc/en/param/deadlock_timeout/) | 1–2147483647 | 1000 |
| [gin\_pending\_list\_limit](https://postgresqlco.nf/doc/en/param/gin_pending_list_limit/) | 64–2147483647 | 4096 |
| [idle\_in\_transaction\_session\_timeout](https://postgresqlco.nf/doc/en/param/idle_in_transaction_session_timeout/) | 0–2147483647 | 0 |
| [join\_collapse\_limit](https://postgresqlco.nf/doc/en/param/join_collapse_limit/) | 1–2147483647 | 8 |
| [lock\_timeout](https://postgresqlco.nf/doc/en/param/lock_timeout/) | 0–2147483647 | 0 |
| [max\_prepared\_transactions](https://postgresqlco.nf/doc/en/param/max_prepared_transactions/) | 0–262143 | 0 |
| [max\_connections](https://postgresqlco.nf/doc/en/param/max_connections/) | 1–262143 | 200 |
| [shared\_buffers](https://postgresqlco.nf/doc/en/param/shared_buffers/) | 16–1073741823 | 31232 |
| [wal\_buffers](https://postgresqlco.nf/doc/en/param/wal_buffers/) | \-1–262143 | 2048 |
| [temp\_buffers](https://postgresqlco.nf/doc/en/param/temp_buffers/) | 100–1073741823 | 1024 |
| [work\_mem](https://postgresqlco.nf/doc/en/param/work_mem/) | 64–2147483647 | 436 |
| [default\_transaction\_isolation](https://postgresqlco.nf/doc/en/param/default_transaction_isolation/) | — | read committed |
| [effective\_cache\_size](https://postgresqlco.nf/doc/en/param/effective_cache_size/) | 1–2147483647 | 524288 |
| [max\_wal\_size](https://postgresqlco.nf/doc/en/param/max_wal_size/) | 2–2147483647 | 1024 |
| [min\_wal\_size](https://postgresqlco.nf/doc/en/param/min_wal_size/) | 2–2147483647 | 80 |
| [wal\_level](https://postgresqlco.nf/doc/en/param/wal_level/) | replica / logical | replica |
| [max\_replication\_slots](https://postgresqlco.nf/doc/en/param/max_replication_slots/) | 5–262143 | 10 |
| [max\_wal\_senders](https://postgresqlco.nf/doc/en/param/max_wal_senders/) | 5–262143 | 10 |
| [max\_worker\_processes](https://postgresqlco.nf/doc/en/param/max_worker_processes/) | 0–262143 | 8 |
| [max\_logical\_replication\_workers](https://postgresqlco.nf/doc/en/param/max_logical_replication_workers/) | 0–262143 | 4 |
| [max\_parallel\_maintenance\_workers](https://postgresqlco.nf/doc/en/param/max_parallel_maintenance_workers/) | 0–1024 | 2 |
| [max\_parallel\_workers](https://postgresqlco.nf/doc/en/param/max_parallel_workers/) | 0–1024 | 8 |
| [max\_parallel\_workers\_per\_gather](https://postgresqlco.nf/doc/en/param/max_parallel_workers_per_gather/) | 0–1024 | 2 |
| [array\_nulls](https://postgresqlco.nf/doc/en/param/array_nulls/) | On/Off | On |
| [backend\_flush\_after](https://postgresqlco.nf/doc/en/param/backend_flush_after/) | 0–256 | 0 |
| [backslash\_quote](https://postgresqlco.nf/doc/en/param/backslash_quote/) | On/Off/safe\_encoding | safe\_encoding |
| [bgwriter\_flush\_after](https://postgresqlco.nf/doc/en/param/bgwriter_flush_after/) | 0–256 | 64 |
| [bgwriter\_lru\_multiplier](https://postgresqlco.nf/doc/en/param/bgwriter_lru_multiplier/) | 1–10 | 2 |
| [default\_transaction\_read\_only](https://postgresqlco.nf/doc/en/param/default_transaction_read_only/) | On/Off | Off |
| [enable\_hashagg](https://postgresqlco.nf/doc/en/param/enable_hashagg/) | On/Off | On |
| [enable\_hashjoin](https://postgresqlco.nf/doc/en/param/enable_hashjoin/) | On/Off | On |
| [enable\_incremental\_sort](https://postgresqlco.nf/doc/en/param/enable_incremental_sort/) | On/Off | On |
| [enable\_indexscan](https://postgresqlco.nf/doc/en/param/enable_indexscan/) | On/Off | On |
| [enable\_indexonlyscan](https://postgresqlco.nf/doc/en/param/enable_indexonlyscan/) | On/Off | On |
| [enable\_material](https://postgresqlco.nf/doc/en/param/enable_material/) | On/Off | On |
| [enable\_memoize](https://postgresqlco.nf/doc/en/param/enable_memoize/) | On/Off | On |
| [enable\_mergejoin](https://postgresqlco.nf/doc/en/param/enable_mergejoin/) | On/Off | On |
| [enable\_parallel\_append](https://postgresqlco.nf/doc/en/param/enable_parallel_append/) | On/Off | On |
| [enable\_parallel\_hash](https://postgresqlco.nf/doc/en/param/enable_parallel_hash/) | On/Off | On |
| [enable\_partition\_pruning](https://postgresqlco.nf/doc/en/param/enable_partition_pruning/) | On/Off | On |
| [enable\_partitionwise\_join](https://postgresqlco.nf/doc/en/param/enable_partitionwise_join/) | On/Off | Off |
| [enable\_partitionwise\_aggregate](https://postgresqlco.nf/doc/en/param/enable_partitionwise_aggregate/) | On/Off | Off |
| [enable\_seqscan](https://postgresqlco.nf/doc/en/param/enable_seqscan/) | On/Off | On |
| [enable\_sort](https://postgresqlco.nf/doc/en/param/enable_sort/) | On/Off | On |
| [enable\_tidscan](https://postgresqlco.nf/doc/en/param/enable_tidscan/) | On/Off | On |
| [exit\_on\_error](https://postgresqlco.nf/doc/en/param/exit_on_error/) | On/Off | Off |
| [from\_collapse\_limit](https://postgresqlco.nf/doc/en/param/from_collapse_limit/) | 1–2147483647 | 8 |
| [idle\_session\_timeout](https://postgresqlco.nf/doc/en/param/idle_session_timeout/) | 0–2147483647 | 900000 |
| [jit](https://postgresqlco.nf/doc/en/param/jit/) | On/Off | On |
| [plan\_cache\_mode](https://postgresqlco.nf/doc/en/param/plan_cache_mode/) | auto / force custom plan / force generic plan | auto |
| [quote\_all\_identifiers](https://postgresqlco.nf/doc/en/param/quote_all_identifiers/) | On/Off | Off |
| [standard\_conforming\_strings](https://postgresqlco.nf/doc/en/param/standard_conforming_strings/) | On/Off | On |
| [statement\_timeout](https://postgresqlco.nf/doc/en/param/statement_timeout/) | 0–2147483647 | 0 |
| [timezone](https://postgresqlco.nf/doc/en/param/TimeZone/) | \-13:59–+14:00 | — |
| [transform\_null\_equals](https://postgresqlco.nf/doc/en/param/transform_null_equals/) | On/Off | Off |
| [max\_locks\_per\_transaction](https://postgresqlco.nf/doc/en/param/max_locks_per_transaction/) | 1–2147483647 | 64 |
| [autovacuum\_vacuum\_cost\_limit](https://postgresqlco.nf/doc/en/param/autovacuum_vacuum_cost_limit/) | \-1–10000 | 200 |
| [checkpoint\_timeout](https://postgresqlco.nf/doc/en/param/checkpoint_timeout/) | 30–86400 | 300 |
| [checkpoint\_completion\_target](https://postgresqlco.nf/doc/en/param/checkpoint_completion_target/) | 0–1 | 0.5 |
| [wal\_compression](https://postgresqlco.nf/doc/en/param/wal_compression/) | On/Off/pglz/lz4/zstd | Off |
| [random\_page\_cost](https://postgresqlco.nf/doc/en/param/random_page_cost/) | 0–10 | 4 |
| [effective\_io\_concurrency](https://postgresqlco.nf/doc/en/param/effective_io_concurrency/) | 0–1000 | 1 |
| [log\_lock\_waits](https://postgresqlco.nf/doc/en/param/log_lock_waits/) | On/Off | Off |
| [log\_temp\_files](https://postgresqlco.nf/doc/en/param/log_temp_files/) | \-1–2147483647 | \-1 |
| [track\_io\_timing](https://postgresqlco.nf/doc/en/param/track_io_timing/) | On/Off | Off |
| [maintenance\_work\_mem](https://postgresqlco.nf/doc/en/param/maintenance_work_mem/) | 1024–2147483647 | 33554432 |

### Changing Parameters

1.  Go to the **Databases** section and click on the cluster.
    
2.  Go to the **Configuration** tab.
    
3.  Click **Modify parameters** next to **Database parameters**.
    

![70e7f8cc F84b 4124 960b C33e2d598237](https://content.hostman.com/assets/b4defc5b-7c71-4682-b31f-23eb7802129d.png?width=1540&height=973)

4.  Adjust the parameters. To read more about each parameter, click **Open description** next to it.
    

![9e882ca8 Ff8a 4e4c A153 94bc49e5c8f8](https://content.hostman.com/assets/c61cebcb-3336-43b5-8903-edda09361c75.png?width=1538&height=1131)

5.  Click **Apply and Restart** at the bottom of the page.
    
6.  Confirm the action.

### Resetting Parameters

If needed, you can restore one or all parameters to their default values.

> [!NOTE]
> Be careful: the parameters will be reset immediately, without additional confirmation.

#### Resetting a Single Parameter

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Reset to default** next to the parameter you want to reset. 

![Modify Parameters 2026 07 20 10 58](https://content.hostman.com/assets/31d12f2e-d166-4344-a0fc-ad2e702950e1.png?width=1563&height=869)

5.  Click **Apply and Restart** at the bottom of the page.
    
6.  Confirm the action.

#### Resetting All Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Restore default settings** at the bottom of the page.
5.  Click **Continue** to confirm. The cluster will be restarted.

![Modify Parameters 2026 07 20 11 01](https://content.hostman.com/assets/9b42f6f7-3139-453b-9eb9-8891b8ce7b03.png?width=1555&height=867)

### Importing and Exporting Parameters

PostgreSQL parameters can be exported to a file and imported into another cluster.

#### Importing Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Import / export** → **Import parameters**.

![Modify Parameters 2026 07 20 11 05](https://content.hostman.com/assets/5a5c52ee-e9bb-49dd-81bb-e31eda2259eb.png?width=1572&height=868)

5.  Select a JSON file containing the parameters.
6.  Click **Apply**.

The parameters file must contain an object with parameter names as keys and their values as strings:

```shell
{
  "parameter_name_1": "parameter_value_1",
  "parameter_name_2": "parameter_value_2"
}
```

If a parameter doesn't exist in the PostgreSQL version you're using, or can't be modified, it will be ignored during import.

#### Exporting Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Import / export** → **Export parameters**.

Your browser will download a JSON file containing the current parameter values.

![Modify Parameters 2026 07 20 11 03](https://content.hostman.com/assets/9f664166-bd52-464e-a7db-7adb427ddce4.png?width=1551&height=858)

## Connecting to the Database

You can connect to your databases using **Adminer** or via terminal. Connecting via Adminer is possible only if the cluster has a public IP address.

### Adminer

You can connect to the database via the built-in web interface Adminer. 

1.  Go to the **Databases** section and click on the cluster.
    
2.  Click the **Web Interface** button and select **Adminer**.
    

![772dffc9 765b 4682 9447 63c0f8b6886c](https://content.hostman.com/assets/4790e609-bb0f-4da8-b768-693a0d4a3aa4.png?width=1560&height=761)

### Terminal

Install the PostgreSQL client:

-   Ubuntu/Debian

```shell
sudo apt install postgresql-client
```

-   Arch

```shell
sudo pacman -S postgresql-libs
```

-   Fedora

```shell
sudo dnf install postgresql
```

There are two ways to connect to a PostgreSQL cluster:

-   via public IP;
-   via private IP.

You can copy the connection command from:

-   the **Dashboard** tab:
    

![6dd75993 D295 4779 9c0e 0cecd159c52d](https://content.hostman.com/assets/047f6d5a-79ab-4893-8cc0-b48db233232b.png?width=1576&height=1506)

-   the **Connection** tab.
    

![D176824e 4a02 42f8 99ca 34a28d591937](https://content.hostman.com/assets/3569d9da-f2dc-4696-a9b9-67aa063eab18.png?width=1552&height=759)

## Role Management

A user with the `CREATE ROLE` privilege can:

-   create new users (`CREATE USER`);
-   create roles (`CREATE ROLE`);
-   manage role memberships (`GRANT ... TO ...`).

### Creating a User

A user is a role that is allowed to log in to the database. Such a role can connect with a username and password.

To create a user with a password, run:

```sql
CREATE USER someuser WITH PASSWORD 'password';
```

Here, `someuser` is the username and `password` is the password.

The new user will appear in the **Users** tab shortly after creation.

### Creating a Role and Assigning It to a User

Instead of granting permissions directly to each user, it is better to create roles with the required privileges and then assign users to these roles.

Let’s create two roles: one with read-only access, and another with read and write access.

Read-only role:

```sql
CREATE ROLE app_reader;
```

Read/write role:

```sql
CREATE ROLE app_writer;
```

Assign a role to a user:

```sql
GRANT app_writer TO someuser;
```

### Schema Configuration

By default, all PostgreSQL tables are created in the public schema. To grant permissions, create a new schema:

```sql
CREATE SCHEMA app_data;
```

Create tables in the new schema:

```sql
CREATE TABLE app_data.users (
  id SERIAL PRIMARY KEY,
  username VARCHAR(50) NOT NULL,
  email VARCHAR(100) UNIQUE NOT NULL
);

CREATE TABLE app_data.orders (
  id SERIAL PRIMARY KEY,
  user_id INTEGER REFERENCES app_data.users(id),
  order_date TIMESTAMP DEFAULT now()
);
```

Grant access to the schema for the previously created roles:

```sql
GRANT USAGE ON SCHEMA app_data TO app_reader;
GRANT USAGE ON SCHEMA app_data TO app_writer;
```

Grant the right to create objects in the schema:

```sql
GRANT CREATE ON SCHEMA app_data TO app_writer;
```

### Table Permissions

Grant read access to all existing tables in the schema:

```sql
GRANT SELECT ON ALL TABLES IN SCHEMA app_data TO app_reader;
```

Grant read/write access:

```sql
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA app_data TO app_writer;
```

Set default permissions for new tables:

```sql
ALTER DEFAULT PRIVILEGES IN SCHEMA app_data 
GRANT SELECT ON TABLES TO app_reader;

ALTER DEFAULT PRIVILEGES IN SCHEMA app_data 
GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO app_writer;
```

And default permissions for new sequences:

```sql
ALTER DEFAULT PRIVILEGES IN SCHEMA app_data 
GRANT USAGE, SELECT ON SEQUENCES TO app_writer;
```

## Creating a Dump

To create a dump, run:

```shell
pg_dump -x 'postgresql://<user>:<password>@<host>:5432/<db>' | gzip > default_db.sql.gz
```

The `-x (--no-privileges)` flag excludes `GRANT` and `REVOKE` commands from the dump, since permission management is handled via the dashboard.

Without this flag, errors may occur when loading the dump, though they won’t affect data restoration.

## Loading a Dump

To load a dump, run:

```shell
zcat default_db.sql.gz | psql 'postgresql://<user>:<password>@<host>:5432/<db>'
```

This command decompresses the dump and passes it to the PostgreSQL client for execution.

## Basic Plan Limitations

The basic database plan (1 CPU / 1 GB RAM / 20 GB NVMe) has the following technical limitations:

-   Additional databases cannot be added
-   Additional users cannot be added
-   The following parameters cannot be configured:
    -   `shared_buffers`
    -   `effective_cache_size`
    -   `maintenance_work_mem`
    -   `max_connections`

# Valkey Management

Source: https://hostman.com/docs/dbaas/valkey/

Valkey is a high-performance, non-relational key-value database. It stores data in memory, which enables very fast request processing. 

Unlike relational database management systems, Valkey doesn't have traditional databases and tables—data is organized into keyspaces, and values can take different structures and types, including strings, lists, sets, and hash tables.

Valkey is an open-source fork of Redis. It maintains compatibility with the Redis protocol, commands, and client libraries, so you can use familiar tools, SDKs, and drivers to connect to a cluster. In most cases, applications that worked with Redis can work with Valkey without any code changes.

Valkey is commonly used for:

-   Data caching
-   Session storage
-   Queue management
-   Messaging between services
-   Real-time data processing

When [creating a cluster](https://hostman.com/docs/dbaas/create-database/), you can choose a Valkey version: 7, 8.1, or 9.1.

## Users and Privileges

In your Hostman dashboard, you can manage Valkey users and their privileges.

### Creating Users

1.  Go to the **Databases** section and click on the cluster.
2.  Open the **Users** tab and click **Add**.
3.  Set the username and password:
    -   Username: 3–64 characters. Letters, numbers, and special characters are allowed.
    -   Password: 8–30 characters. Letters, numbers, and special characters are allowed.
4.  (Optional) Configure the user’s privileges. You can also leave the default parameters and change them later at any time.
5.  Click **Create**.

### Modifying Privileges

To update the privileges of an existing user:

1.  Go to the **Databases** section and click on the cluster.
2.  Open the **Users** tab.
3.  Click the three dots next to the user.
4.  Select **Privileges**.
5.  Choose the required privileges. You can grant access to a specific database or grant the same privileges for all databases by enabling Identical for all databases in the top right.

### Available Privileges

| **Privilege** | **Description** |
| --- | --- |
| `READ` | Read data from the database. |
| `WRITE` | Write and modify data. |
| `ADMIN` | Run administrative commands (e.g., manage configuration, flush database). |
| `BITMAP` | Work with bit arrays. |
| `BLOCKING` | Use blocking commands (e.g., `BLPOP`, `BRPOP`). |
| `CONNECTION` | Manage connections and connection settings. |
| `DANGEROUS` | Access potentially dangerous commands (e.g., `FLUSHALL`, `MIGRATE`). |
| `GEO` | Work with geospatial data (e.g., `GEOADD`, `GEORADIUS`). |
| `HASH` | Work with hash tables. |
| `HYPERLOGLOG` | Work with the `HyperLogLog` data type. |
| `FAST` | Use low-latency commands. |
| `KEYSPACE` | Get key lists and key metadata. |
| `LIST` | Work with lists. |
| `PUBSUB` | Use the publish/subscribe mechanism (`PUBLISH`, `SUBSCRIBE`). |
| `SCRIPTING` | Execute Lua scripts in Valkey. |
| `SET` | Work with sets. |
| `SORTEDSET` | Work with sorted sets. |
| `SLOW` | Use commands that may take longer to execute. |
| `STREAM` | Work with data streams (`XADD`, `XREAD`). |
| `STRING` | Work with strings. |
| `TRANSACTION` | Use transactions (`MULTI`, `EXEC`). |

### Changing User Password

You can change the user password:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Users** tab.
3.  Click the three dots next to the user.
4.  Select **Change password**.
5.  Enter a new value and save changes.

## Database Parameters

You can change database settings to optimize its performance. 

By default, the database is created with the parameters that are suitable for most tasks and will ensure the performance of the selected configuration. However, if your project requires specific settings, you can change them as you wish. 

Be careful and change parameters only if you are sure of their purpose. Incorrect configuration can negatively affect the operation of the database and its performance.

### Parameters List

| **Parameter** | **Valid Values** | **Default Value** |
| --- | --- | --- |
| [client-output-buffer-limit normal](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L764) | — | 0 0 0 |
| [client-output-buffer-limit pubsub](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L764) | — | 33554432 8388608 60 |
| [maxmemory-policy](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L373) | — | allkeys-lru |
| [slowlog-log-slower-than](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L648) | 0–600000000 | 10000 |
| [slowlog-max-len](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L653) | 0–4294967296 | 128 |
| [timeout](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L73) | 0–3600000000 | 0 |
| [databases](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L115) | 0–2147483647 | 16 |
| [save](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L120) | — | 900 1 |
| [appendonly](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L432) | On/Off | On |
| [appendfsync](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L479) | — | everysec |
| [tcp-keepalive](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L76) | 0–3600 | 300 |
| [notify-keyspace-events](https://github.com/redis/redis/blob/46319094dba97e1e5627ad52687d8d9dab26c070/redis.conf#L659) | — | — |

### Changing Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Adjust the parameters. To read more about each parameter, click **Open description** next to it.
5.  Click **Apply** at the bottom of the page.

### Resetting Parameters

If needed, you can restore one or all parameters to their default values.

> [!NOTE]
> Be careful: the parameters will be reset immediately, without additional confirmation.

#### Resetting a Single Parameter

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Reset to default** next to the parameter you want to reset. 
5.  Click **Apply and Restart** at the bottom of the page.
6.  Confirm the action.

#### Resetting All Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Restore default settings** at the bottom of the page.
5.  Click **Continue** to confirm. The cluster will be restarted.

### Importing and Exporting Parameters

Valkey parameters can be exported to a file and imported into another cluster.

#### Importing Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Import / export** → **Import parameters**.
5.  Select a JSON file containing the parameters.
6.  Click **Apply**.

The parameters file must contain an object with parameter names as keys and their values as strings:

```shell
{
  "parameter_name_1": "parameter_value_1",
  "parameter_name_2": "parameter_value_2"
}
```

If a parameter doesn't exist in the Valkey version you're using, or can't be modified, it will be ignored during import.

#### Exporting Parameters

1.  Go to the **Databases** section and click on the cluster.
2.  Go to the **Configuration** tab.
3.  Click **Modify parameters** next to **Database parameters**.
4.  Click **Import / export** → **Export parameters**.

Your browser will download a JSON file containing the current parameter values.

## Connecting to the Database

To work with your Valkey cluster, install the `redis-cli` or `valkey-cli` utility. Valkey is compatible with Redis, so you can connect using either standard Redis clients and commands or Valkey tools.

### Installing redis-cli

The `redis-cli` utility is included with Redis and can be installed via package managers:

-   Ubuntu/Debian

```shell
sudo apt install redis-tools
```

-   macOS

```shell
brew install redis
```

-   Arch Linux

```shell
sudo pacman -S redis
```

-   CentOS/RHEL

```shell
sudo yum install redis
```

After installation, check the client version:

```shell
redis-cli -v
```

### Installing valkey-cli

To use `valkey-cli`, install the Valkey package. This will also install the command-line utility:

-   Ubuntu/Debian

```
sudo apt install valkey
```

-   macOS

```
brew install valkey
```

-   Arch Linux

```
sudo pacman -Syu valkey
```

-   CentOS/RHEL

```shell
sudo yum install epel-release
sudo yum install valkey
```

### Connection Command

There are two ways to connect to a Valkey cluster:

-   via public IP;
-   via private IP.

You can copy the connection command from:

-   the **Dashboard** tab:
    

![C5808e03 025d 4c98 B004 9d8d5be1935a](https://content.hostman.com/assets/ca2f0bae-e2a2-4c18-b4bc-0749219c6296.png?width=1535&height=1491)

-   the **Connection** tab:
    

![5b57323e 447a 45a3 A3c1 09e1d9bd6962](https://content.hostman.com/assets/52f286b0-7911-44f5-b2bf-f8f0072eb77c.png?width=1546&height=846)

## Creating a Dump

Valkey is compatible with Redis, so you can use most existing tools from the Redis ecosystem for backup and migration.

To export Valkey data, use the `redis-dump-go` utility, available for different architectures. Download the binary for your architecture from the [official repository](https://github.com/yannh/redis-dump-go/releases).

To create a dump, run:

```sql
REDISDUMPGO_AUTH='password' ./redis-dump-go -host <cluster-ip> -port 6379 -user default > redis-dump.txt
```

Here, `REDISDUMPGO_AUTH` is the password for cluster access.

## Importing a Dump

To import data, use `redis-cli` or `valkey-cli` in `--pipe` mode, which supports loading large datasets:

```shell
redis-cli -h <cluster-ip> -p 6379 --user default --pass 'password' --pipe < redis-dump.txt
```

Or with `valkey-cli`:

```shell
valkey-cli -h <cluster-ip> -p 6379 --user default --pass 'password' --pipe < redis-dump.txt
```

# Database Users

Source: https://hostman.com/docs/dbaas/database-users/

When creating a cluster, the user gen\_user is automatically created. You can create new [database](https://hostman.com/managed-database/) users, grant them different rights to different databases, and generally manage them on the **Users** tab.

## Creating Users

To create a new user:

1.  Go to the **Database** section and click on the cluster.
    
2.  On the **Users** tab click **Add**.
    
3.  Specify the parameters such as username, password and hosts.
    
4.  Configure the privileges for this user (you can modify them later).
    
5.  Click **Create**.
    

The **Use the same privileges for all databases** option is enabled by default. If necessary, you can turn it off and then select a specific database from the list to configure user privileges.

## Configuring Users

To change the privileges of an already created user:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Users** tab.
    
3.  Click on the three dots and select **Privileges**.
    
4.  Set the privileges and save changes.

If the user privileges should be different for different databases, turn off the **Use the same privileges for all databases** option, and then configure the privileges by selecting the required databases from the list.

## Changing User Password

You can change the user password for connecting to the database on the **Users** tab.

1.  Go to the **Database** section and click on the cluster.
    
2.  In the **Users** tab click on the three dots for the desired user and select **Change password**.
    
3.  Enter a new value and save changes.

# Connect to the Database

Source: https://hostman.com/docs/dbaas/connecting-to-database/

You can connect to the [database](https://hostman.com/managed-database/) using standard tools.

For example, to connect via the command line using the mysql utility, use the command below, specifying your database details:

```shell
mysql -u db_user -p password -h host -P port -D db_name
```

You can find and copy the details:

-   From the **Dashboard**
    

![0db698af E5ee 44a1 A438 0eeb18423ce0](https://content.hostman.com/assets/732be951-c5be-4eb5-a2d3-c697379852db?width=1510&height=1128)

-   From the **Connection** tab 
    

![62f51749 Cc4c 40f8 87a8 E20a890fc104](https://content.hostman.com/assets/578d889c-b07c-49bd-9c51-132f0ec19996?width=1489&height=850)

## Web interfaces

You can work with the database using the built-in web interfaces to choose from: Adminer or phpMyAdmin, as well as OpenSearch Dashboards for OpenSearch databases and ClickHouse Query for ClickHouse.

1.  Go to the **Database** section and click on the cluster.
    
2.  Click on the **Web Interface** in the top right and select the preferred interface.
    

![D055f360 Bb7b 45a7 977d Bd93b8876536](https://content.hostman.com/assets/f636a9b0-af98-4766-b02d-848707747291?width=1490&height=762)

3.  Enter the database details (IP, username and password).

# Backups

Source: https://hostman.com/docs/dbaas/backup/

When you create a new [database](https://hostman.com/managed-database/) cluster, you can enable automatic backups. One backup copy of your data will be created daily and the previous copy deleted. You can always change the schedule for automatic backups or disable them completely.

## Creating a Backup

You can create manual backups in your dashboard.

To do this:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Backup** tab and click on the **Create backup** or **N backups** link.

![4d856629 Fce7 4adc 8f15 Aa98fc6e0af8](https://content.hostman.com/assets/6e26d186-4b2e-4dd6-9d62-ddec2fbcd674.png?width=1569&height=766)

3.  Click **Create backup.**
4.  Add a comment if necessary and click **Create**.

![453a51fe Ee73 4c64 B4e0 10060fde331e](https://content.hostman.com/assets/c5fe5729-77be-46f6-ab40-a7bfcf8bd032.png?width=1751&height=769)

While the backup is being created, other actions with backups will be disabled. Creating a copy will take a few minutes.

## Restoring Data From Backups

To restore data from a backup:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Backup** tab and click on the **N backups** link.

![4d856629 Fce7 4adc 8f15 Aa98fc6e0af8](https://content.hostman.com/assets/6e26d186-4b2e-4dd6-9d62-ddec2fbcd674.png?width=1569&height=766)

3.  Hover over the backup you need and click the **Restore** icon.
4.  Confirm the action.

![1cccf512 3873 41a8 A751 9081db97d9ae](https://content.hostman.com/assets/98817289-8475-4610-b0ae-b86d99e5ee6c.png?width=1744&height=770)

## Configuring Automatic Backups

You can enable, disable and schedule automatic database backups in the **Backups** tab of the cluster.

### Enabling and Scheduling Backups

To enable automatic backups or change their schedule:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Backups** tab and click **Configure schedule**.

![A5e36ab0 Ff56 412d 82a8 4ee9ac1196ec](https://content.hostman.com/assets/7daf3228-01bb-4264-a372-eb61b2d5e3eb.png?width=1569&height=766)

3.  Enable the backups and set the parameters: 
    -   the frequency of creating copies (daily, weekly and monthly), 
    -   the number of copies, 
    -   the start date of scheduled backups.
4.  Click **Save**.

![3a25e03a 25f8 4c38 84d5 4d65eea4972f](https://content.hostman.com/assets/71b889ab-4568-4359-9652-dd557ef015ac.png?width=1578&height=821)

### Disabling Backups

To disable automatic backups:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Backups** tab and click **Configure schedule**.
3.  Move the toggle switch to the **Off** position.
4.  Click **Save**.

![4eff6d64 F298 4cec 8732 F43b5348b69f](https://content.hostman.com/assets/ffb20406-039f-4673-a446-836bd5264e42.png?width=1580&height=769)

## Deleting a Backup

To delete a backup:

1.  Go to the **Database** section and click on the cluster.
2.  Go to the **Backup** tab and click on the **N backups** link.
3.  Click on the three dots next to the backup you want to delete and select **Delete**.

![9da3b37d A0f5 45e8 A1dc 74a4bae25eac](https://content.hostman.com/assets/b458ef67-3455-4c40-b0e8-5af5fb739d7e.png?width=1744&height=763)

# Network Settings

Source: https://hostman.com/docs/dbaas/network-settings/

Each [cloud database](https://hostman.com/managed-database/) cluster has a private IP address from a particular private network. You can choose whether the cluster should also have a public IP as well as move the database cluster to another private network.

## Private networks

You can move the cluster to another private network.

1.  Go to the **Database** section and click on the cluster.
    
2.  Go to the **Network** tab.
    
3.  Click **Configure** next to the private network. 
    
4.  Select one of the existing networks or create a new one.
    
5.  Click **Transfer**.
    

Transferring the cluster will take some time. Normally, 10 GB transfers within 1 minute. 

After the transfer is complete, the database will be restarted. 

Overall downtime is around 5-10 minutes.

## Public and private IPs

When you create a database cluster, it is assigned a [private and public IP address](https://hostman.com/blog/public-vs-private-ip-addresses-what-s-the-difference/) by default.

You can restrict access to the cluster via public IP so the cluster is only accessible within the private network. 

1.  Go to the **Database** section and click on the cluster.
    
2.  Go to the **Network** tab.
    
3.  Disable the **Allow access by public IP address** option. 
    
4.  Confirm disabling public access.
    

> [!NOTE]
> Later on, you can restore public access to the cluster, however, a new public IP address will be issued for the cluster.

# Cluster Configuration

Source: https://hostman.com/docs/dbaas/configuration/

You can upgrade your [DBaaS plan](https://hostman.com/dbaas/) thus upgrading the configuration of your cluster.

> [!NOTE]
> Please note that it is not possible to downgrade the DBaaS plan. 

1.  Go to the **[Databases](https://hostman.com/managed-database/)** section and click on the cluster.
    
2.  Go to the **Configuration** tab and click **Change plan**.
    
3.  Select new configuration for your cluster and click **Save and reboot.**
    
4.  Confirm changing the plan.
    

The cluster will be restarted, after which the changes will take effect.

# Prometheus Exporter

Source: https://hostman.com/docs/dbaas/prometheus-exporter/

The Prometheus Exporter is a component that collects metrics from the operating system and databases and provides them in a format that Prometheus understands. The exporter helps monitor the state of database clusters, server load, and other important real-time information.

## Exporter Setup

Exporter access details are available on the cluster page in the **Dashboard** tab.

![Exporter](https://content.hostman.com/assets/44eabc12-b3e5-4a9d-8c27-27f67a8dbd93.png?width=776&height=618)

When using public exporters, access to metrics requires basic authentication.

Example request to a public exporter:

```shell
curl -u admin:'password' -s https://dbs-exporter.hostman.com/exporter_id/service/metrics
```

## Limitations

-   Metric collection is available **only in BGP networks** (Germany and the Netherlands).
-   Exporters are available on two endpoints:
    

-   `:9100`: Server metrics (e.g., load, CPU, and memory usage);
    
-   `:9308`: Database metrics.
    

## Exporter Types

There are two types of exporters:

-   **Public exporters** are exposed over HTTPS and accessible via a domain name.
-   **Private exporters** are accessible only within a private BGP network.

|  | **Public exporters** | **Private exporters** |
| --- | --- | --- |
| **Metric Access** | Via domain name | Via IP address within the private network |
| **Public IP required** | No | No |
| **Authentication** | Basic Auth | Not required |

## Exporters Used

| **DBaaS Cluster** | **Exporter** |
| --- | --- |
| MySQL | [MySQL Server Exporter](https://github.com/prometheus/mysqld_exporter) |
| PostgreSQL | [PostgreSQL Server Exporter](https://github.com/prometheus-community/postgres_exporter) |
| RabbitMQ | [RabbitMQ Exporter](https://github.com/kbudde/rabbitmq_exporter) |
| Valkey | [Prometheus Valkey & Redis Metrics Exporter](https://github.com/oliver006/redis_exporter) |
| Kafka | [JMX Exporter](https://github.com/prometheus/jmx_exporter) |
| OpenSearch | [Prometheus Exporter Plugin for OpenSearch](https://github.com/opensearch-project/opensearch-prometheus-exporter) |
| ClickHouse | [Built-in Exporter](https://clickhouse.com/docs/interfaces/formats/Prometheus) |

### Checking Exporter Version

To find the version of a specific exporter, use the command:

```shell
curl -s http://private_IP:9308/metrics | grep '_exporter_build_info'
```

You’ll receive output similar to:

```shell
# HELP postgres_exporter_build_info A metric with a constant '1' value labeled by version, revision, branch, goversion from which postgres_exporter was built, and the goos and goarch for the build.

# TYPE postgres_exporter_build_info gauge

postgres_exporter_build_info{branch="HEAD",goarch="amd64",goos="linux",goversion="go1.23.3",revision="a324fe37bca5193a293118b940b3df7ab3a8505c",tags="unknown",version="0.16.0"} 1
```

The value `version="0.16.0"` indicates the exporter version.

**Note:** The OpenSearch exporter is built manually, so it is not possible to determine its version using this command.

## Example Configuration

Let’s look at configuring Prometheus on a cloud server to collect metrics from a PostgreSQL cluster.

#### 1\. Ensure Network Connectivity

Make sure that the database cluster and the cloud server are in the same private network.

#### 2\. Install Prometheus

Go to the [Prometheus releases page](https://github.com/prometheus/prometheus/releases) and download the latest version. For example:

```shell
wget https://github.com/prometheus/prometheus/releases/download/v3.7.2/prometheus-3.7.2.linux-amd64.tar.gz
```

Extract the archive:

```shell
tar -xzf prometheus-*.tar.gz
```

Navigate to the directory:

```shell
cd prometheus-3.7.2.linux-amd64
```

#### 3\. Configure Prometheus

Open the configuration file:

```shell
nano prometheus.yml
```

Add the database cluster’s private IP address and ports to the `scrape_configs` section:

```yaml
- job_name: 'linux-metrics'
  static_configs:
    - targets: ['192.168.0.5:9100']

- job_name: 'postgres-metrics'
  static_configs:
    - targets: ['192.168.0.5:9308']
```

Here, `192.168.0.5` is the private IP of the PostgreSQL cluster.

When using a **public exporter**, the scrape configuration looks as follows:

```yaml
- job_name: 'postgres-public'
  scheme: https
  metrics_path: /exporter_id/service/metrics
  static_configs:
    - targets: ['dbs-exporter.hostman.com']
  basic_auth:
    username: 'admin'
    password: 'password'
```

To collect **server metrics**, use `/exporter_id/node-exporter/metrics` instead of `/exporter_id/service/metrics`.

Full configuration example:

```yaml
global:
  scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          # - alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: "prometheus"

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    static_configs:
      - targets: ["localhost:9090"]
       # The label name is added as a label `label_name=<label_value>` to any timeseries scraped from this config.
        labels:
          app: "prometheus"
  - job_name: 'linux-metrics'
    static_configs:
      - targets: ['192.168.0.5:9100']

  - job_name: 'postgres-metrics'
    static_configs:
      - targets: ['192.168.0.5:9308']

  - job_name: 'postgres-public'
    scheme: https
    metrics_path: /exporter_id/service/metrics
    static_configs:
      - targets: ['dbs-exporter.hostman.com']
    basic_auth:
      username: 'admin'
      password: 'password'
```

#### 4\. Start Prometheus

Run Prometheus with the specified configuration file:

```shell
./prometheus --config.file=prometheus.yml
```

By default, the Prometheus web interface will be available at:

```shell
http://<cloud_server_IP>:9090
```

#### 5\. Check Exporter Status

In the Prometheus web interface, go to **Status** → **Targets**.

Make sure that all `job_name` entries are visible and have the status **UP**.

For a basic check, you can run the following query on the **Graph** tab:

```shell
up
```

If everything is working correctly, you’ll see all connected exporters listed with their corresponding `job_name` values.

![Aef4c1cb 737e 4414 82fd C9acc0500161.png](https://content.hostman.com/assets/1c00f8ab-49b3-4aa6-8b97-dedccbd35b79.png?width=2610&height=1434)

_List of metrics in the [Prometheus](https://prometheus.io/) interface_

# Action History

Source: https://hostman.com/docs/dbaas/history/

You can view the actions performed on the [database](https://hostman.com/managed-database/) cluster in the **History** tab.

![Image1](https://content.hostman.com/assets/8fb35166-51c3-41bf-9aa0-57a8b2bb2087?width=1480&height=940)

Hostman logs the following actions:

-   Creating a cluster
    
-   Changing configuration
    
-   Creating a database
    
-   Creating a user
    
-   Changing database parameters
    
-   Changing public access
    
-   Enabling and disabling automatic backups
    
-   Creating a backup manually
    
-   Deleting a backup

# Delete Clusters and Databases

Source: https://hostman.com/docs/dbaas/delete/

**To delete a specific [database](https://hostman.com/managed-database/) in the cluster**: 

1.  Go to the **Database** section and click on the cluster.
    
2.  Go to the **Databases** tab.
    
3.  Click on the three dots next to the database. 
    
4.  Click **Delete**.
    
5.  Confirm the action.
    

**To delete the whole cluster**, with all databases and database users within it:

1.  Go to the **Database** section.
    
2.  Click on the three dots and click **Delete database**.
    

![Image1](https://content.hostman.com/assets/63b274e7-646a-4526-ad29-17ee6f43a916?width=1480&height=849)

3.  Confirm the action.
    

Or:

1.  Go to the **Database** section and click on the cluster.
    
2.  Go to the **Configuration** tab.
    
3.  Click **Delete database**.
    

![Image2](https://content.hostman.com/assets/7b4b3732-ed8c-4daa-b4d9-d805fa6d37cc?width=1483&height=885)

4.  Confirm the action.

# Cloud Servers

Source: https://hostman.com/docs/cloud-servers/

[Cloud servers](https://hostman.com/cloud-server/) are a way to host your data where you get full control over a virtual server, including **root access** and all system settings. You can scale server resources up or down as needed: add capacity (CPU, memory, and storage) when traffic grows and reduce it (CPU and memory) when the load drops. The server cost adjusts accordingly.

To deliver reliable performance, we use modern hardware, fast **NVMe storage**, and high-performance processors.

> [!NOTE]
> The CPU frequency you may see in server console benchmarks does not reflect the processor’s actual performance. The virtualization layer reports the **base clock speed** and does not account for **Turbo Boost**.
>
> In practice, the platform’s CPUs always run with Turbo Boost enabled, ensuring the performance level specified in your plan.

# Create Cloud Servers

Source: https://hostman.com/docs/cloud-servers/create-server/

To create a cloud server, click **Create** **Server** in the [Cloud Servers](https://my.hostman.com/servers) section of your dashboard.

## 1\. Choose a Region

Select where your server should be located. 

![Create Server 2026 08 20 11 41](https://content.hostman.com/assets/f1832a3c-e879-499c-9697-4530064f36ba.png?width=755&height=491)

## 2\. Choose an Image

Select the image you want to install on the server. 

-   In the **Operating system** tab you’ll find Unix-based distributions such as Ubuntu, Debian, CentOS, and others without additional software. You can select the specific version you need. 
    

![Create Server 2026 08 20 11 41 (1)](https://content.hostman.com/assets/2fc0136a-b6db-45fa-abfa-a0ac6329fd7a.png?width=753&height=594)

-   [Marketplace](https://hostman.com/marketplace/) offers a selection of pre-configured images and apps such as LAMP, Docker, GitLab etc. When available, you can also specify the operating system version.
    

![Create Server 2026 08 20 11 42](https://content.hostman.com/assets/7d78ada6-782c-4d44-90a4-101cf6ea3481.png?width=756&height=702)

-   The **Custom images** tab allows you to upload your own Unix-based image into the dasboard and install it on the cloud server. You can also select one of the images already uploaded. 

![Create Server 2026 08 20 11 43](https://content.hostman.com/assets/f5018f37-1217-4c75-8dd5-234097739fa4.png?width=753&height=542)

## 3\. Choose Server Configuration

Select server configuration choosing the amount of RAM, CPU and disk size you need. 

If later on your server needs more resources you will be able to increase the plan. However, changing the plan to a lesser one will not be possible.

Should you need several servers with identical configurations, you can create them all at once by specifying the number of servers. Keep in mind that you need to have enough balance to pay for all the servers you’re creating.

![Create Server 2026 08 28 12 25](https://content.hostman.com/assets/b5aab2ef-ff6e-40e5-a3bc-5442c0b03861.png?width=750&height=643)

## 4\. Configure Network Settings

Decide whether the server should have a public IP and needs to be in a private network. This can be changed further on.

![Create Server 2026 08 20 11 44 (1)](https://content.hostman.com/assets/bfbbe563-a917-4d56-bad0-55968b7b06a3.png?width=761&height=592)

For private networks, you can choose one of the following options:

-   Select one of the existing private networks on your account. We will only display the networks available for this server, i.e. created in the same region.
    
-   Add a new private network. In this case, you’ll need to set the IP address range for it with the following parameters.
    

| Available ranges | Maximum CIDR size | Minimum CIDR size |
| --- | --- | --- |
| 10.0.0.0/x | /8 | /28 |
| 192.168.0.0/x | /16 | /28 |
| 172.16.0.0/x | /12 | /28 |

You can also manually assign a private IP for this server and set up a custom hostname.

## 5\. Enable Backups

In the **Security** section, the **Backups** option is automatically selected. 

![E7ee22f4 D5e1 4156 98af 70890e5d7866](https://content.hostman.com/assets/badbd07d-bf29-4f43-a06a-8719e31f0e6a.png?width=753&height=359)

If you leave it enabled, we will automatically create an auto backup rule for creating one copy of your data daily. Each new copy will replace the previous one.

You can change the auto backup plan later on or disable it altogether.

The backup cost is $0.07 for 1 GB of disk space so the total depends on the disk size.

If you don’t need backups at the moment, unselect the option. You can enable backups later at any time.

## 6\. Configure Authorization Methods

This step is optional. 

By default, you can connect to the server via SSH using your `root` password. For extra security, you can:

-   **Set up the SSH keys authentication**. You can choose one of the existing SSH keys that you’ve already uploaded on your account or add a new one. More information about how to create an SSH key can be found [here](https://my.hostman.com/sshkeys/create).
-   **Disable password authentication for SSH**. If you disable password authentication at this stage and later decide to enable it, you will need to remove or rename the `/etc/ssh/sshd_config.d/50-cloud-init.conf` file.

If you want to keep using password authentication, skip this step.

![31b0dadb 909a 497f 9026 72a18d986ef2](https://content.hostman.com/assets/ab8a4173-8122-4b14-9b1d-5842617648a3.png?width=756&height=453)

## 7\. Add Cloud-Init Script

This step is optional. 

Cloud-init scripts allow you to configure the server at the installation stage. To use cloud-init, paste your script in the form. The script should begin with `#cloud-config` or `#!/bin/sh`. More about cloud-init can be found [here](https://hostman.com/docs/cloud-servers/cloud-init).

![8630a03d 8093 4913 9e2c E45236080e8d](https://content.hostman.com/assets/a7850777-9fde-472f-b49b-c9183f417c36.png?width=752&height=558)

If you don’t need to use cloud-init, leave it blank and proceed to the next step.

## 8\. Finalize Details

Edit the server name and comment if necessary and choose the project to add the server to. These settings can be changed later on.

![Create Server 2026 08 20 11 45](https://content.hostman.com/assets/281e4477-8727-4ecb-8b33-490770b8f55b.png?width=760&height=448)

Check all your chosen parameters and if everything is correct, click **Create**.

The server will be installed in a couple of minutes. The moment it’s ready, we will send you an email notification.

You can find the server IP address, copy your `root` password and a quick command for SSH connection in the server **Dashboard**.

![508425dc E16a 432e A61e 6a06346b8173](https://content.hostman.com/assets/e477092a-3a84-44d0-a14d-8095eadbd0ae.png?width=1517&height=1155)

# Cloud-init

Source: https://hostman.com/docs/cloud-servers/cloud-init/

[Cloud-init](https://cloudinit.readthedocs.io/en/latest/index.html) is a [cloud server](https://hostman.com/cloud-server/) configuration tool that allows you to pass user parameters (user-data) when initializing a virtual machine, thus speeding up and automating the server configuration process.

With cloud-init you can customize the server configuration, install the software, create directories and users, manage access and much more. 

## Formats

You can pass cloud-init scripts as `#cloud-config` text files or `#!/bin/sh` shell scripts.

When using shell scripts, keep in mind:

-   The shell script will be automatically converted to `cloud-config` with the `runcmd` directive;
    
-   `runcmd` is executed once, so if you edit the script and reboot the server, the script will not be executed.
    

If you need to execute the script at every boot, use `cloud-config` scripts with the `bootcmd` directive.

## Important Notes

-   Scripts are run as `root`, so you do not need to add `sudo` to the commands. 
    
-   All files and directories created will belong to the `root` user. If you want another user to have access, set the appropriate permissions for that user in the script.
    
-   The script runs automatically, so you cannot use commands that require action from the user. For commands that require confirmation during execution, use the `-y` flag (for example, `apt upgrade -y`).
    
-   The script execution log is written to the `/var/log/cloud-init-output.log` file.
    
-   When using third-party server images, `cloud-init` may not function correctly.
-   On Ubuntu, `cloud-init` will create the `ubuntu` user by default if there is no `users` directive. To avoid it, use the directive: `users: []`.
    

## Passing the Script

You can pass the `cloud-init` script:

-   When you [create a new server](https://hostman.com/docs/cloud-servers/create-server/). The `cloud-config` parameters will be applied during installation.
    

![Image5](https://content.hostman.com/assets/1c39d9ac-8d10-455a-9e72-8c45e2cc1e19?width=734&height=409)

-   When you [reinstall the server](https://hostman.com/docs/cloud-servers/os-reinstall/). The parameters will be applied during installation.
    

![Image1](https://content.hostman.com/assets/e547994a-3b2a-4cd3-8daf-adf6152f1e54?width=1920&height=1395)

-   At the reboot. In this case, you can pass the script in the **Plan** section and then reboot the server. For the parameters to apply, you must restart the system with the command: `cloud-init clean --reboot`.
    

![Image2](https://content.hostman.com/assets/412d506b-0e81-412a-884f-d65d0204fb27?width=1920&height=958)

## Editing the Script

You can modify the already uploaded `cloud-init` script in the server settings.

For the updated parameters to be applied at the next reboot, you must reboot the system with the command: `cloud-init clean --reboot`.

1.  Go to the **Plan** tab.
    
2.  Click **Edit** in the **Cloud-init** block.
    
3.  Make the changes and save them.
    

![Image2](https://content.hostman.com/assets/412d506b-0e81-412a-884f-d65d0204fb27?width=1920&height=958)

The script will be applied the next time the server is rebooted. 

## Cloud-config examples

The file must begin with the `#cloud-config` in the first line.

**Installing packages**

```shell
#cloud-config
package_update: true
packages:
 - apache2
 - mariadb-server
 - mariadb-client
```

**Creating users**    

```shell
#cloud-config
users:
  - name: username
  - name: new_username
```

**Adding SSH keys**

```shell
#cloud-config
ssh_authorized_keys:
  - ssh-rsa PUBLIC_KEY username@server
```

You can add several keys at once:

```shell
#cloud-config
ssh_authorized_keys:
  - ssh-rsa PUBLIC_KEY username@server
  - ssh-rsa PUBLIC_KEY_2 username2@desktop
```

**Creating a sudo user, adding SSH keys, and configuring the bash shell**

```shell
#cloud-config
users:
  - name: username
    groups: sudo
    shell: /bin/bash
    sudo: ['ALL=(ALL) NOPASSWD:ALL']
    ssh-authorized-keys:
      - PUBLIC_KEY username@server
      - PUBLIC_KEY_2 username2@desktop
```

**Installing LAMP on Ubuntu**

```shell
#cloud-config
package_update: true
packages:
  - apache2
  - php-mysql
  - mysql-server
  - libapache2-mod-php
  - php-gd
  - php-curl
runcmd:
  - [ find, /var/www, -type, d, -exec, chmod, 2775, {}, \; ]
  - [ find, /var/www, -type, f, -exec, chmod, 0664, {}, \; ]
write_files:
  - path: /var/www/html/phpinfo.php
    owner: www-data:www-data
    content: |
      ""
```

Once the configuration is complete, the link `http://server_ip/phpinfo.php` will display a page with PHP parameters.

More examples can be found in the [cloud-init documentation](https://cloudinit.readthedocs.io/en/latest/reference/examples.html#cloud-config-examples).

## Shell Scripts Examples

The script must start with the `#!/bin/sh` in the first line.

**Installing packages**

```shell
#!/bin/sh
apt -y update
apt -y install fail2ban
```

**Installing LAMP on CentOS**

```bash
#!/bin/sh
##Installing PHP 7.2
yum -y install epel-release
yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install https://rpms.remirepo.net/enterprise/remi-release-7.rpm
yum-config-manager --enable remi-php72
yum update -y
yum install -y php php-mcrypt php-cli php-gd php-curl php-mysql php-ldap php-zip php-process php-ldap php-mbstring
##Installing MariaDB 11.02
wget https://downloads.mariadb.com/MariaDB/mariadb_repo_setup
chmod +x mariadb_repo_setup
bash mariadb_repo_setup
yum install -y httpd mariadb-server
##Enabling the services
systemctl start mariadb
systemctl enable mariadb
systemctl start httpd
systemctl enable httpd
##Setting permissions
chmod 2775 /var/www
find /var/www -type d -exec chmod 2775 {} \;
find /var/www -type f -exec chmod 0664 {} \;
## Outputting phpinfo
echo "" > /var/www/html/phpinfo.php
## Opening the port
iptables -t filter -I INPUT -p tcp --dport 80 -j ACCEPT
```

# Connect to the Server

Source: https://hostman.com/docs/cloud-servers/connect-to-server/

You can find the credentials for `root` access to the server (IP address and password) on the server's Dashboard. You can also copy the SSH connection command directly from there.

![13943d26 F5c9 4c60 9191 Cb4ac02ea3e2](https://content.hostman.com/assets/c76559b7-132a-44a1-8ef6-1bed483faea7.png?width=1557&height=1394)

## Connecting via SSH

You can work with the server via SSH using the [web console](https://hostman.com/docs/cloud-servers/web-console/) in the dashboard, but it may not always be convenient. It’s better to connect to the server via SSH using specialized software, depending on your computer’s operating system. The software may either be built-in or need to be installed separately.

### Linux, macOS, Windows 10

For Linux or macOS users, you can use the built-in **terminal** utility. On Windows, starting with version 10 (build 1809), there is a built-in SSH client, and you can use **Windows PowerShell** to connect via SSH.

To connect to the [cloud server](https://hostman.com/cloud-server/):

1.  Open a terminal or PowerShell and enter the following command, replacing it with your server's IP address:

```shell
ssh root@server_IP_address
```

For example:

```shell
ssh root@166.1.227.189
```

2.  On your first connection, you’ll see a message asking for confirmation. Type `yes` and press **Enter**.
3.  Next, you’ll be prompted for a password. Enter the password carefully, as the characters will not be displayed on the screen (you can copy the password from the Dashboard and paste it).
4.  Press **Enter**.

If all the details are correct, the connection will be established.

### Windows Without OpenSSH

When using older versions of Windows, you’ll need an additional SSH client, such as PuTTY, to connect via SSH. You can download it from the [official website](https://www.chiark.greenend.org.uk/~sgtatham/putty/) and install on your machine.

To connect using PuTTY:

1.  Launch PuTTY.
2.  Enter the connection details:

-   -   **Host Name**: the server’s IP address (from the Dashboard)
    -   **Port**: 22

You can save the session settings by entering a convenient name (e.g., `vds1`) in the **Saved Sessions** field and clicking **Save**.

3.  Click **Open**.
4.  Upon the first connection, an additional window will appear to confirm the connection. Click **Yes**.
5.  A console window will open, where you need to enter your login and password:

-   -   `login as`: enter `root`.
    -   `password`: enter the password (the characters will not be shown on the screen).

6.  Press **Enter**.

If the credentials are correct, the connection will be established. Now you can enter commands directly in the console window.

## Connecting via SFTP

SFTP (SSH File Transfer Protocol) is a secure protocol for working with files on a remote server. It allows you to transfer files, create directories, manage permissions, etc. Working with SFTP is similar to working with FTP, but the connection is established over the secure SSH protocol.

FTP (File Transfer Protocol) is an older method for transferring files and is considered generally unsafe. It lacks encryption and has several security flaws that make it less suitable for usage, especially when dealing with sensitive data. We recommend using SFTP instead of FTP.

> [!NOTE]
> By default, Hostman servers allow SFTP connections. If you wish to use FTP, you need to set up FTP on your server manually.

For establishing a connection, you need an SFTP client, such as FileZilla, WinSCP, Cyberduck etc.

To connect, use the following credentials:

-   **Host**: Your server IP address (you can find this on the server's Dashboard)
-   **Username**: `root` or another user created on the server
-   **Password**: The password for that user
-   **Port**: 22

If RSA key authentication is used, you will also need to provide the passphrase (if you set it when creating the RSA key) and upload the contents of the public key.

> [!NOTE]
> We do not recommend connecting via SFTP as the `root` user. Not only does this pose security risks, but it can also be inconvenient.
>
> When you connect as root, you’ll start in the `root` home directory (`/root`). This means you’ll have to navigate through the file system to reach your project folders.
>
> Besides, any files you upload as `root` will be assigned the user and group `root:root`, which may prevent the web server from accessing them. This could lead to access errors for those new files.

### Using FileZilla for SFTP Connections

You can download FileZilla client from the [official website](https://filezilla-project.org/index.php).

#### Connecting to the Server

1.  Launch the program and enter the necessary connection settings:
    

-   -   **Host**: The IP address of your server.
    -   **Username**: Either `root` or a user account created on the server.
    -   **Password**: The password for the user.
    -   **Port**: 22 (21 for FTP)

![Filezilla Wbgvva Yo B8](https://content.hostman.com/assets/8affa00d-0d84-4af2-8b67-8b0df211fbb1.png?width=905&height=203)

_[FileZilla](https://filezilla-project.org/) interface_

2.  Click the **Quickconnect** button. If all the information is correct, the connection will be established.
    
3.  The right side of the window will display the user account on the server, while the left side shows navigation through your local computer’s folders.
    

![Filezilla Ydszw Fcyrv](https://content.hostman.com/assets/705c5133-02c5-4ed3-ac9e-2f63e449b2be.png?width=1369&height=919)

_[FileZilla](https://filezilla-project.org/) interface_

**Note**: FTP connections with encryption enabled won’t work by default. You need to configure FileZilla to either use "Use explicit FTP over TLS if available" (this is the default option) or "Use plain FTP" in the **File** → **Site Manager** settings.

### Uploading Files to the Server

-   To upload files to the server, navigate to the desired directory on the server (right side of the window), then select the files or folders on your computer (left side of the window).
-   Right-click on the selected items and choose "Upload to server" from the context menu.
-   Alternatively, you can drag and drop files from the left to the right side.
-   The file upload progress will be shown at the bottom of the window.

### Downloading Files from the Server

-   On the left side of the window, choose the directory where you want to save the files (e.g., "Downloads").
-   On the right side, locate the files/folders you want to download. Right-click them and select "Download".
-   The files will be downloaded to the directory you selected.
-   You can also use drag-and-drop to download files from the server to your local computer.

### Saving the Connection Settings

To avoid re-entering server details every time you connect, you can save the connection in the settings.

-   If the connection is already established:
    
    -   Go to **File** → **Copy current connection to Site Manager**.
    -   In the **Site Manager** window that opens, give a name to this connection.
    -   For FTP connections, make sure "Use explicit FTP over TLS if available" is selected under **Encryption**.
    -   Since the other settings are already filled in, click **OK** to save the connection.
-   If no connection is currently active:
    
    -   Go to **File** → **Site Manager**.
    -   In the **Site Manager** window, click **New Site** and give the connection a name.
    -   Enter the necessary settings: **Host** (server IP), **Port** (21 for FTP, 22 for SFTP), **Username**, and **Password** (your server credentials).
    -   For FTP connections, ensure that "Use explicit FTP over TLS if available" is selected under **Encryption**, and set "Passive mode" under the **Transfer Settings** tab.
    -   Click **OK** to save the connection, or **Connect** to save and immediately connect to the server.

In the future, you can connect to the saved server with just one click by selecting the saved connection from the list of sites in the **Site Manager**.

# Project Migration

Source: https://hostman.com/docs/cloud-servers/migration/

Moving your project to Hostman doesn't have to mean downtime or lost data. This section walks you through everything you need to plan and complete a smooth migration.

-   [Preparing for Migration](https://hostman.com/docs/cloud-servers/migration/preparing/)
-   [Support-Assisted Migration](https://hostman.com/docs/cloud-servers/migration/support-assisted/)
-   [Manual Migration](https://hostman.com/docs/cloud-servers/migration/manual/)
-   [Migrating with aaPanel](https://hostman.com/docs/cloud-servers/migration/aapanel/)
-   [Migrating with FASTPANEL](https://hostman.com/docs/cloud-servers/migration/fastpanel/)
-   [Migrating with Hestia](https://hostman.com/docs/cloud-servers/migration/hestia/)
-   [Migrating with ISPConfig](https://hostman.com/docs/cloud-servers/migration/ispconfig/)
-   [Migrating with Plesk](https://hostman.com/docs/cloud-servers/migration/plesk/)

# Preparing for Migration

Source: https://hostman.com/docs/cloud-servers/migration/preparing/

Before you migrate your project to Hostman—whether you do it yourself or ask our support team to handle it—a bit of preparation will make the process faster and reduce the risk of downtime. Here's what we recommend.

## Back Up Your Project

Before starting the migration, create a backup of your project (or your entire server) and store it somewhere outside your current hosting provider: locally on your machine, or in separate cloud storage. 

This way, you'll always have access to your data, even if your subscription with your previous provider expires before the migration is complete.

## Prepare a Migration Brief

You know your project better than anyone else. To get started, we'll ask for access credentials and site names, but the more detail you provide about your project's setup, the fewer adjustments will be needed later.

When submitting a migration request, include:

-   Root access to your server via SSH.
-   A list of all domains (and their aliases) that need to be migrated.
-   The root directory paths for each site, along with any additional folders they use.
-   Which site uses which database.
-   Any details that could affect how the project runs after migration, for example, an external database, a custom application, a non-standard import/export setup, or integrations with third-party services.
-   Any other information that could help us complete the migration smoothly.

## Plan Ahead

Avoid scheduling your migration for the last paid day with your current provider. If something goes wrong during the process, your project could be unavailable for several hours—or even days.

Request your migration at least 7–10 days before your current plan expires. This gives you enough time to:

-   Copy all your files to the new server without rushing.
-   Complete the necessary configuration.
-   Thoroughly test your project on the new server, using a temporary domain or a local hosts file entry.
-   Add any files that weren't transferred automatically.
-   Finish any remaining setup.

If possible, avoid making changes to your project while it's being migrated and tested. If you can't pause updates entirely, coordinate with our support team on a specific date and time—ideally during a period of low traffic—to sync the final version of your data. 

> [!NOTE]
> Note that we can only perform this final data sync during business hours.

Also, hold off on launching any campaigns or driving traffic to the migrated site (for example, ad campaigns) until the migration is fully complete. Migrations don't always go exactly as planned, and it's best to have some buffer time.

## Don't Rush to Delete Data With Your Previous Provider

Even if everything looks fine after migration, keep your account and data with your previous provider active for a while. Minor issues sometimes surface a few days later, and having a working copy of your project on the old server makes it much easier to troubleshoot.

## Turn Off the Old Server Before Your Final Check

Once you're confident the migration is complete, disable (but don't delete) your old server, then test your project again. This confirms that everything is running from the new server and that no resources are still being pulled from your previous provider.

## Point Your Domain to Hostman

Once you've verified that your project is fully migrated and working correctly, update your domain's DNS settings to point to your Hostman server.

# Support-Assisted Migration

Source: https://hostman.com/docs/cloud-servers/migration/support-assisted/

Our support team can migrate your project to Hostman for you—whether you're moving from another provider or between servers within Hostman.

## What's Included

As part of a support-assisted migration, we'll:

-   Install a control panel, if needed.
-   Copy your site files.
-   Copy your database.
-   Connect the database to your site.
-   Migrate cron jobs, if they're explicitly listed in your request.

## Supported Technologies

We can migrate projects built with:

-   PHP
-   Node.js
-   Python
-   Ruby

**We don't migrate:**

-   Projects built with ASP.NET.
-   Projects built with website builders.
-   Mail servers.
-   Bots.
-   Applications running in Docker containers.

If your project uses a different stack, check with our support team to confirm whether migration is possible.

If your project requires code changes or configuration updates to run correctly on the new server, you'll need to make those changes yourself or with the help of a third-party specialist.

## How Migration Works

We migrate projects one of two ways, depending on your setup. 

### Option 1: Full Disk Image

This works for any type of project and keeps your existing environment intact—including custom configurations, installed software, and system-level settings.

To migrate this way, one of the following needs to be true:

-   You can provide a server image in one of these formats: `raw`, `qcow2`, `qed`, `qcow`, `luks`, `vdi`, `vmdk`, `vpc`, `vhdx`.
-   You can grant us access to your current provider's dashboard, with the ability to create and mount backups.
-   You can grant us access to your current provider's dashboard, with the ability to boot from a recovery disk.

In the last case, your original server will experience some downtime during the transfer—how long depends on the size of your disk.

Steps:

1.  We copy your disk image.
2.  We deploy the disk image and set up your site on a temporary domain.
3.  You check that everything works correctly on the temporary domain.
4.  You point your domain to the new server.

### Option 2: Site Files and Database

This option is only available if the destination server has a control panel installed (for example, FASTPANEL or HestiaCP). If your project needs specific environment tuning, you'll need to handle that yourself or bring in a third-party specialist.

1.  We copy your site files and database.
2.  We deploy your site on a temporary domain.
3.  You check that everything works correctly on the temporary domain.
4.  You point your domain to the new server.

## Requesting a Migration

To request a migration, message our support team via the chat in your dashboard or email us from the address registered to your account.

If you're migrating from another provider, first [sign up for Hostman](https://hostman.com/signup/) and [create a server](https://hostman.com/docs/cloud-servers/create-server/)—you'll need somewhere to migrate to before we can get started.

If you're migrating between two Hostman accounts, submit your request from the **source** account. We'll then reach out to confirm the transfer with the destination account.

In your request, include:

-   The IP address of the source server.
-   SSH or FTP login credentials (if using FTP, also include database access details—for example, phpMyAdmin credentials). 
-   The file path on the source server.
-   Login credentials for the destination server.

We'll confirm the estimated migration time in the chat. If any complications come up, we may need more time—we'll let you know if that happens.

Once we notify you that your project has been deployed, check that it's working correctly, then migrate your domain following [our domain setup guide](https://hostman.com/docs/domains/add/). 

If you're migrating between two Hostman accounts, [move the domain](https://hostman.com/docs/domains/move-between-accounts/) to the destination account and point its A record to the new server's IP address. If the domain uses Hostman nameservers, you can do this [from the **Domains & SSL** section](https://hostman.com/docs/domains/manage-dns/#usage-example). Otherwise, you'll need to do this [from your nameserver provider's dashboard](https://hostman.com/docs/domains/dns-records-in-other-providers/).

> [!NOTE]
> If you need to sync your database right before the domain switch, coordinate the timing with us via chat.

## After Migration

Once migration is complete, your project will reflect its state at the time we received your request. If you notice anything different about how your migrated site behaves compared to the original, contact us within 14 days. We can make corrections as long as a backup from the original platform is still available.

We also strongly recommend [changing your root password](https://hostman.com/docs/cloud-servers/root-password-reset/) after migration.

# Manual Migration

Source: https://hostman.com/docs/cloud-servers/migration/manual/

If you'd rather migrate your project yourself, follow the steps below to set up your server and migrate your project.

## Step 1. Install the Required Software

If you don't plan to use a control panel, we recommend [installing LAMP automatically](https://hostman.com/my/servers/create?createServerEntrySource=servers-cta-button&zone=fra-1&configurator=97&cpu=10&gpu=0&ram=6&drive=80&os=99&software=17) when you create your server.

LAMP (Linux, Apache, MySQL, PHP) is the software stack needed to run and correctly display dynamic websites and web applications.

![Create Server 2026 07 31 10 58](https://content.hostman.com/assets/da3721d8-04ee-4cff-b3e3-382f6ff87e2d.png?width=750&height=543)

Alternatively, you can create a server with a clean OS and install LAMP manually later.

## Step 2. Set Up Your Domain

Once your server is ready, [add your domain](https://hostman.com/docs/domains/add/) in the dashboard under **[Domains & SSL](https://hostman.com/my/domains)**.

If you're migrating between two Hostman accounts, [move the domain](https://hostman.com/docs/domains/move-between-accounts/) to the destination account and point its A record to the new server's IP address. If the domain uses Hostman nameservers, you can do this [from the **Domains & SSL** section](https://hostman.com/docs/domains/manage-dns/#usage-example). Otherwise, you'll need to do this [from your nameserver provider's dashboard](https://hostman.com/docs/domains/dns-records-in-other-providers/).

## Step 3. Upload Your Site Files

The easiest way to upload your files is via SFTP, using an app like FileZilla.

When connecting, use:

-   Your server's IP address.
-   Your server login and password.
-   Port 22.

Upload your files to the correct directory:

-   If LAMP was installed automatically when you created your server, upload your files to `/var/www/html`.
    
-   If you installed LAMP manually, the directory depends on your configuration. For example, it can be `/var/www/site1/public_html`.
    

## Step 4. Set Up Your Database

[Connect to your server via SSH](https://hostman.com/docs/cloud-servers/connect-to-server/) and create a database:

```shell
mysql
```

Run the following commands. We recommend using the database name, username, and password already specified in your site's configuration file.

Create the database:

```sql
CREATE DATABASE 'database_name';
```

Create a database user:

```sql
CREATE USER 'username'@'localhost' IDENTIFIED BY 'password';
```

Grant the user full privileges on the database:

```sql
GRANT ALL PRIVILEGES ON 'database_name'.* TO 'username'@'localhost';
```

Reload privileges:

```sql
FLUSH PRIVILEGES;
```

Upload your database dump to the server (for example, to the `/var/www/` directory via SFTP), then import it:

```shell
mysql -u"username" database_name -p"password" < /var/www/dump_name.sql
```

If you'd like a GUI for managing your database, you can also install phpMyAdmin on your server.

# Migrating with aaPanel

Source: https://hostman.com/docs/cloud-servers/migration/aapanel/

After you install aaPanel on the server, the panel's login address and credentials will be displayed in the console.

![Nzfnv Cp4 J9](https://content.hostman.com/assets/1ea032f0-5e8f-4296-bb26-1ee38cdc0692.png?width=692&height=222)

The first time you log in to aaPanel, you'll need to choose a server configuration by selecting the software stack you want installed.

Once the configuration is complete, you're ready to add your site in aaPanel.

## Step 1. Adding a Site

1.  Go to the **Website** section and click **Add site**.
    
2.  In the **Domain name** field, enter your site's address. The **Website path** (home directory) is filled in automatically, but you can change it if needed.
    
3.  Leave **Apply for SSL** checked to issue a Let's Encrypt certificate. If you're planning to use your own certificate, uncheck this option.
    
4.  If you'll be uploading files over FTP, select **Create** under **FTP**.  Enter a username and password in the **FTP User** field, or leave the default values.
    
    You can skip this step if you plan to use the panel's built-in file manager instead. 
    

5.  If your site uses a database, select the database type under **Database**, for example, **MySQL** (the available options depend on your chosen configuration). Enter a username (which also serves as the database name) and password in the **DB User** field, or leave the default values. We recommend using the credentials already specified in your site's configuration file.
    
    If your configuration uses a username that's different from the database name, skip this step and create the database separately in the **Databases** section instead (see below).
    
6.  Once you've filled in all the fields, click **Confirm**.
    

![Aa Panel Linux Panel Website 2026 08 07 12 54](https://content.hostman.com/assets/c5879845-4725-4b5a-9c12-d32bb3e8c46a.png?width=992&height=786)

_Adding a site in [aaPanel](https://www.aapanel.com/)_

aaPanel will then display the credentials for the FTP user and database it created. Make sure to copy these somewhere safe.

## Step 2. Uploading Site Files

You can upload files either through the aaPanel's built-in file manager or via an FTP connection.

### Using the File Manager

1.  Open the **Files** section.
    
2.  Go to your site's home directory.
    
3.  Click **Upload**.
    
4.  Select the files and folders that you want to upload and click **Confirm Upload**.
    

![Aa Panel Linux Panel Files 2026 08 07 13 03](https://content.hostman.com/assets/97dead02-9387-4577-a22e-5d12db778900.png?width=1920&height=869)

_File manager in [aaPanel](https://www.aapanel.com/)_

### Using FTP

To connect over FTP, you'll need an FTP user set up on the server.

If you didn't create one while adding the site, do it now:

1.  Go to the **FTP** section.
    
2.  Click **Add FTP**.
    
3.  Enter a username, password, and the path to the site's home directory.
    
4.  Click **Confirm**.
    

Then connect to your server—for example, using FileZilla—with the following settings:

-   **Host**: your server's IP address
-   **Username**: the FTP username you created
-   **Password**: the user's password
-   **Port**: 21

This connects you to the site's home directory, where you should upload your files.

## Step 3. Importing a Database Dump

Go to the **Databases** section.

If you didn't create a database while adding the site, do it now: click **Add DB**, enter a database name, username, and password (you can find these in your site's configuration file), then click **Confirm**.

![Aa Panel Linux Panel Databases 2026 08 07 13 10](https://content.hostman.com/assets/c68f6d98-3b86-416b-89a9-aebd03a2622f.png?width=672&height=525)

_Creating a database in [aaPanel](https://www.aapanel.com/)_

To import a dump:

1.  In the **Databases** section, click **Import** in the **Backup** column.
    

![Aa Panel Linux Panel Databases 2026 08 07 13 12](https://content.hostman.com/assets/ec07d2d6-2c3a-449e-9ee1-73d80795980a.png?width=1920&height=869)

_Databases section in [aaPanel](https://www.aapanel.com/)_

2.  Click **Upload from local** and select the database dump on your computer.
    
3.  Click **Upload**.
    

Alternatively, you can import the dump through phpMyAdmin:

1.  In the **Databases** section, click the **phpMyAdmin** button.
    

![Aa Panel Linux Panel Databases 2026 08 07 13 44](https://content.hostman.com/assets/24d6aa4a-1d50-48b2-af9b-6fd413f298da.png?width=1920&height=869)

_Databases section in [aaPanel](https://www.aapanel.com/)_

2.  Click **Public access**.
    
3.  Enter the database username and password.
    
4.  Import the dump using the phpMyAdmin interface.
    

> [!NOTE]
> Keep in mind that for your site to work, your domain's A record needs to point to your server's IP address.

# Migrating with FASTPANEL

Source: https://hostman.com/docs/cloud-servers/migration/fastpanel/

This guide covers migrating your project using [FASTPANEL](https://fastpanel.direct/)—one of the control panels you can [install directly from your Hostman account](https://hostman.com/my/servers/create?createServerEntrySource=servers-cta-button&zone=fra-1&configurator=97&cpu=10&gpu=0&ram=6&drive=80&os=99&software=51). 

To deploy your site on a server with FASTPANEL installed, follow the steps below.

1.  Log in to FASTPANEL and click **Create site**.
    
2.  Choose how you want to create the site. This guide covers creating a PHP site.
    

![195 133 93 247 Fastpanel Hosting Control 2026 08 07 12 35](https://content.hostman.com/assets/38b753ea-c4e5-4113-b9f3-c2aec047a293.png?width=1475&height=1034)

_Creating a site in [FASTPANEL](https://fastpanel.direct/)_

3.  Enter your domain, then click **Next step**.
    

![195 133 93 247 Fastpanel Hosting Control 2026 08 07 12 36](https://content.hostman.com/assets/a464fc62-f60e-4616-81ab-2de6fe323054.png?width=1475&height=808)

_Creating a site in [FASTPANEL](https://fastpanel.direct/)_

4.  Review the suggested configuration and adjust it if needed by clicking the pencil icon next to the relevant section.
    
    In the **User** section, we recommend keeping the **Create new** option selected, so your site runs under a dedicated panel user instead of the superuser, `fastuser`.
    
    In the **Database** section, click on the pencil icon and set up the preferred database name, database user name (in the **Login** field) and user password.
    
5.  Click **Create site**.
    

![195 133 93 247 Fastpanel Hosting Control 2026 08 07 12 37](https://content.hostman.com/assets/b8c319dc-60a0-4bd5-a75d-302cc0327b68.png?width=1475&height=1097)

_Creating a site in [FASTPANEL](https://fastpanel.direct/)_

6.  Click **Site card**.
    
7.  Go to the **Files** menu.
    

![195 133 93 247 Fastpanel Hosting Control 2026 08 07 12 40 2026 08 07 12 41](https://content.hostman.com/assets/4256b1b7-ff34-4a3b-ab31-436317a247f3.png?width=1679&height=1431)

_Viewing the site card in [FASTPANEL](https://fastpanel.direct/)_

8.  Upload your site files to the server.
    

![195 133 93 247 Fastpanel Hosting Control 2026 08 07 12 39](https://content.hostman.com/assets/5e4b2ef4-87c1-415f-977f-17041cc236af.png?width=1519&height=808)

_File manager in [FASTPANEL](https://fastpanel.direct/)_

9.  Update your site's configuration file with the new database connection details.
    
10.  Go back to your site's card and open the **Databases** menu.
     

![195 133 93 247 Fastpanel Hosting Control 2026 08 07 12 40 2026 08 07 12 40](https://content.hostman.com/assets/02b188a3-e19d-41ea-9df4-e77ea6096fff.png?width=1679&height=1426)

_Viewing the site card in [FASTPANEL](https://fastpanel.direct/)_

11.  Open phpMyAdmin and import your database dump to the server.
     

![195 133 93 247 Fastpanel Hosting Control 2026 08 07 12 41](https://content.hostman.com/assets/16625748-b742-471b-b6c5-9a6325b929cb.png?width=1679&height=808)

_Databases section in [FASTPANEL](https://fastpanel.direct/)_

12.  Check that your site is working correctly.
     

> [!NOTE]
> Keep in mind that for your site to work, your domain's A record needs to point to your server's IP address.

# Migrating with Hestia

Source: https://hostman.com/docs/cloud-servers/migration/hestia/

This guide covers migrating your project using [HestiaCP](https://hestiacp.com/)—one of the control panels [you can install directly](https://hostman.com/my/servers/create?createServerEntrySource=servers-cta-button&zone=fra-1&configurator=97&cpu=10&gpu=0&ram=6&drive=80&os=99&software=73) from your Hostman account. 

## Step 1. Create a User

Go to `https://your_server_IP:8083` and log in as `admin`. You'll find the password on your server's dashboard.

The administrative user `admin` has elevated privileges, so for security reasons, we don't recommend adding sites under this account. Instead, you should create a regular user first.

1.  Go to the **USER** section.
2.  Click **Add User**. 
3.  Fill in the required fields: **Username**, **Contact Name**, **Email**, and **Password**.
4.  Click **Save**.

You can now log in to the panel as the user you just created: go to the **USER** section and click on the login icon next to the new user.

![Users in Hestia](https://content.hostman.com/assets/be367d29-7ff7-4ea4-b71c-fc309083dcc1.png?width=1454&height=581)

_USER section in [Hestia Control Panel](https://hestiacp.com/)_

## Step 2. Add Your Domain

Add your domain to Hestia:

1.  Go to the **WEB** section.
2.  Click **Add Web Domain**. 
3.  Enter your domain.
4.  Click **Save**.

Now, let's configure it.

In the **WEB** section, click on the domain to open its settings.

We recommend issuing an SSL certificate for the domain at this stage. To do this, enable the following options:

-   **Enable SSL for this domain**
-   **Use Let's Encrypt to obtain SSL certificate**
-   **Enable automatic HTTPS redirection**

If you already have a certificate for the domain, you can upload the certificate files instead—in that case, leave **Use Let's Encrypt** disabled.

![Editing domain settings in Hestia](https://content.hostman.com/assets/975dcd1d-f2aa-4c7c-b494-7d3cfae60038.png?width=1453&height=1092)

_Domain settings configuration in [Hestia Control Panel](https://hestiacp.com/)_

You can also use the **Advanced Options** button to add an FTP account, adjust web server settings, or select a PHP version.

Click **Save** when done.

## Step 3. Upload Your Site Files

When you create your user, Hestia automatically sets up a directory for your site files: `/home/username/web/domain_name`.

To access your files, click the folder icon in the top menu.

![Web section in Hestia](https://content.hostman.com/assets/ea42b036-f16a-4503-ab07-c040eb10e832.png?width=1467&height=531)

_WEB section in [Hestia Control Panel](https://hestiacp.com/)_

Once in the file manager, you'll land in your user's home directory by default. Navigate to `/web/domain_name/public_html`, then upload your files using the `Add Files` button.

![File Manager in Hestia Control Panel](https://content.hostman.com/assets/df9a5765-00ef-43e3-9a9a-3aea90f82f4d.png?width=1561&height=690)

_File Manager in [Hestia Control Panel](https://hestiacp.com/)_

The file manager can unpack ZIP archives directly, which is handy if your files are archived.

For large file volumes, [uploading via FTP/SFTP](https://hostman.com/docs/cloud-servers/connect-to-server/#connecting-via-sftp) is usually more reliable—connect using the username and password of your Hestia user. You can also [use SSH](https://hostman.com/docs/cloud-servers/connect-to-server/#connecting-via-ssh) for the same purpose.

When done, return to the Hestia interface by clicking **Exit to Control Panel** in the top right corner.

## 4\. Import Your Database

First, create a database in Hestia:

1.  Go to the **DB** section.
    
2.  Click **Add Database**. 
    
3.  Enter the database details: 
    

-   Database name
    
-   Database user’s name
    
-   Database user’s password
    

5.  Click **Save**.
    

![Creating a database in Hestia](https://content.hostman.com/assets/4b16065d-4454-44f9-a72c-4d42fce59a36.png?width=1460&height=849)

_Creating a database in [Hestia Control Panel](https://hestiacp.com/)_

Now, import the database dump:

1.  Open the **DB** section.
    
2.  Click on the **phpMyAdmin** button.
    
3.  Log in with the database user’s credentials you just set up.
    
4.  Go to the **Import** tab and import the database.
    

> [!NOTE]
> Hestia restricts access to the PMA interface via the server IP address (`https://server-ip-address/phpmyadmin/`). Make sure to use the hostname instead (for example, `https://host.mydomain.com/phpmyadmin/`).

You can also import the dump via the command line, by connecting to your server [over SSH](https://hostman.com/docs/cloud-servers/connect-to-server/#connecting-via-ssh).

## Step 5. Point Your Domain at the Server

For the site to be reachable, your domain's A record must point to your server's IP address. Update the record in the DNS settings of your domain registrar or DNS provider.

DNS changes can take up to 24 hours to propagate, although in most cases they take effect much sooner.

After propagation, open your domain in a browser to confirm that the migrated site loads correctly and that it connects to the database.

# Migrating with ISPConfig

Source: https://hostman.com/docs/cloud-servers/migration/ispconfig/

[ISPConfig](https://www.ispconfig.org/) is a control panel that lets you manage websites, FTP accounts, and databases on your server from a browser. This guide walks you through moving an existing project to your server: pointing the domain at the server, creating the website, uploading the site files over FTP, and importing the database.

## Before You Begin

Make sure that:

-   ISPConfig is installed on your server. At Hostman, you can [install ISPConfig](https://hostman.com/my/servers/create?createServerEntrySource=servers-cta-button&zone=fra-1&configurator=97&cpu=10&gpu=0&ram=6&drive=80&os=99&software=49) with one click.
-   You have access to the DNS settings of your domain.
-   You have a local copy of your site files and a dump of your database.
-   You have an FTP client installed on your computer, such as FileZilla.

## Step 1. Add the Domain

1.  In the DNS settings for your domain, create an A record pointing to your server's IP address. Do this wherever your domain's nameservers are managed—usually your registrar or DNS provider.
    
2.  In the ISPConfig panel, open the **Sites** section and click **Add new website**.
    
3.  Enter your domain name in the **Domain** field.
    
4.  Select the **Let's Encrypt SSL** checkbox if you want to issue a free certificate.
    
5.  Choose the PHP mode in the **PHP** field and **PHP Version** your project requires.
    
6.  You can leave the remaining settings at their defaults and return to them later. Otherwise, configure them now on the other tabs. For example:
    

-   On the **Redirect** tab, set up redirects.
    
-   On the **SSL** tab, add your own certificate instead of issuing a Let's Encrypt one.
    
-   On the **Statistics** tab, enable AWStats or another statistics tool.
    
-   On the **Backup** tab, set the backup interval for the site and the number of copies to keep.
    

8.  When you're done, click **Save**.
    

## Step 2. Upload the Site Files

To upload the site files to the server, you first need to create an FTP user.

1.  Open the **FTP-Accounts** section and click **Add new FTP-User**.
2.  Select the website you're creating the user for.
3.  Set a username and password.
4.  Click **Save**.
5.  Connect to the server over FTP using the credentials you just set, and upload your files to the web directory.

## Step 3. Create a Database and Import the Dump

1.  Open the **Database Users** section and click **Add new User**.
    
2.  Enter a database username and password.
    
3.  Click **Save**.
    
4.  Go to **Databases** and click **Add new Database**.
    
5.  Fill in the database details:
    

-   Select the website you're creating the database for.
    
-   Enter the database name.
    
-   Select the database user you created earlier.
    
-   Enable remote access if you need it. If you do, you can also specify the remote IP address allowed to connect.
    

7.  Click **Save**.
    
8.  Go to `https://your_server_ip:8081/phpmyadmin` and log in to phpMyAdmin with the credentials of the user you created.
    
9.  Import your database dump.
    
10.  Update your site's configuration files with the new database connection details: the database name, username, and password.
     

## Verify the Migration

Open your domain in a browser and check that the site loads and connects to the database correctly.

Keep in mind that for the site to work, your domain's A record must point to your server's IP address. DNS changes can take up to 24 hours to propagate, although in most cases they take effect much sooner.

# Migrating with Plesk

Source: https://hostman.com/docs/cloud-servers/migration/plesk/

[Plesk](https://www.plesk.com/) is a control panel that lets you host and manage websites from a browser, without connecting to the server over SSH. This guide walks you through moving an existing project to your server: uploading the site files, creating a database, and importing a database dump.

## Before You Begin

Make sure that:

-   Plesk is fully installed on your server. Installation takes several minutes; wait for it to finish before opening the panel.
-   You have a local copy of your site files and a dump of your database.
-   You know the database name, username, and password used in your site's configuration file.

## Step 1. Add a Domain and Upload the Site Files

1.  In the Plesk interface, open **Websites & Domains** and click **Add Domain**.
    
2.  Choose how you want to create the website. This guide uploads the files of an existing site from your computer, so select **Upload files**.
    

![Adding a domain in Plesk](https://content.hostman.com/assets/edfb455e-d16a-4cb2-aebe-d732ed83b768.png?width=1890&height=869)

_Adding a domain in [Plesk](https://www.plesk.com/)_

3.  Enter the domain name you want to host on the server.
4.  Click **Add Domain**.

![Adding a domain in Plesk](https://content.hostman.com/assets/403adc21-5866-4576-8ddc-e0c755b545ee.png?width=1892&height=869)

_Adding a domain in [Plesk](https://www.plesk.com/)_

Plesk will perform the required configuration, add the domain, and open the **Files** section—the built-in file manager.

5.  Click the plus icon and select **Upload File** or **Upload Directory**, depending on how your project is packaged.
    

![File Manager in Plesk](https://content.hostman.com/assets/5e7237b0-fced-4ee2-b1e5-172b7bb5c00c.png?width=1901&height=869)

_File Manager in [Plesk](https://www.plesk.com/)_

6.  Upload the site files to the server.
    

Once the upload finishes, the files are stored in the document root of the domain you just added.

## Step 2. Create a Database and Import the Dump

1.  Open the **Databases** section.
    
2.  Click **Add Database**.
    
3.  Fill in the database details: the database name, the username, and the user's password.
    

We recommend entering the same credentials that your site's configuration file already uses. This way you won't need to edit the configuration after the migration.

![Creating a Database in Plesk](https://content.hostman.com/assets/ad465a14-3bcb-4211-badf-db1ab83b8f84.png?width=1896&height=869)

_Creating a database in [Plesk](https://www.plesk.com/)_

4.  In the **Related site** field, select the domain you added in **Step 1**.
    
5.  Click **Create Database**.
    
6.  Click **Import dump** and upload your database dump to the server.
    

![Databases in Plesk](https://content.hostman.com/assets/31892674-02e2-4c1d-93ee-14c130aafa58.png?width=1880&height=869)

_Databases section in [Plesk](https://www.plesk.com/)_

You can also import the dump through phpMyAdmin: click **phpMyAdmin**, open the **Import** section, and upload the file there.

## Step 3. Point Your Domain at the Server

For the site to be reachable, your domain's A record must point to your server's IP address. Update the record in the DNS settings of your domain registrar or DNS provider.

DNS changes can take up to 24 hours to propagate, although in most cases they take effect much sooner. After propagation, open your domain in a browser to confirm that the migrated site loads correctly and that it connects to the database.

# Server Configuration

Source: https://hostman.com/docs/cloud-servers/server-configuration/

You can manage your [cloud server](https://hostman.com/cloud-server/)’s configuration in the **Plan** tab.

Here, you can:

-   Select a new plan for the server thus changing the disk space, the amount of RAM and the number of CPU cores;
-   Add up to 3 additional disks to your server;
-   Delete disks;
-   Increase the disk size.

> [!NOTE]
> Operations with disks are not available if a snapshot is created for the server.

## Changing the Server Plan

> [!NOTE]
> You can only upgrade your server’s plan. Downgrading is not possible as reducing the disk size can damage the file system.

To change your server's plan:

1.  Go to the **Plan** tab.
2.  Click **Select plan**. 
3.  Choose a new plan for the server.
4.  Click **Save and reboot** to apply the changes.
5.  Confirm the action.

## Adding New Disks

To add an additional disk to your server:

1.  Go to the **Plan** tab.
2.  Click **Add disk**.
3.  Set the desired disk size and click **Add**.
4.  Confirm the action.

You will see the new disk in the dashboard.

### Configuring the Disk in the OS

Now you have to add the disk in the operating system. 

On Linux, disk setup typically consists of the following steps:

1.  Create a partition on the disk
2.  Create a filesystem
3.  Mount the disk (if needed)
4.  Add an entry to `/etc/fstab`

#### Disk Naming Notes

If your server was created before May 2025, disks will be named like `vd*`. On servers created after May 2025, disks will be named `sd*`. 

The disk name displayed in the dashboard may not always be correct. Make sure to check disk names on your system with:

```shell
lsblk
```

Example output:

```shell
NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
loop1    7:1    0 63.9M  1 loop /snap/core20/2318
loop2    7:2    0   87M  1 loop /snap/lxd/29351
loop3    7:3    0 50.9M  1 loop /snap/snapd/24505
loop4    7:4    0 63.8M  1 loop /snap/core20/2599
loop5    7:5    0 89.4M  1 loop /snap/lxd/31333
loop6    7:6    0 50.9M  1 loop /snap/snapd/24718
sda      8:0    0   15G  0 disk 
└─sda1   8:1    0   15G  0 part /
sdb      8:16   0   10G  0 disk 
vda    252:0    0    1M  1 disk
```

Here, `sdb` is the newly added disk. 

In the examples below, we’ll prepare the `sdb` disk, as `sda` is the main system disk, and `vda` is reserved for `cloud-init` by default.

Replace `sdb` in the commands with the actual disk name on your system.

#### Step 1. Creating a Partition

To create a partition, use `fdisk`:

```shell
fdisk /dev/sdb
```

Inside `fdisk`:

-   Press `n` to create a new partition
-   Choose `p` for a primary partition
-   Leave the remaining options at their default values (press **Enter**)
-   Press `w` to write the changes and exit

![1964dcf0 B9a0 4c0f 9787 34ce903ce011](https://content.hostman.com/assets/561a81ca-719a-4b72-845f-b515809a875e.png?width=726&height=498)

Run the command again to verify the partition was created:

```shell
lsblk
```

In our example, the new partition will be `sdb1`.

```shell
NAME    MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda       8:0    0   25G  0 disk
├─sda1    8:1    0 24.9G  0 part /
├─sda14   8:14   0    4M  0 part
└─sda15   8:15   0  106M  0 part
sdb       8:16   0   10G  0 disk
└─sdb1    8:17   0   10G  0 part
vda     252:0    0    1M  1 disk
```

#### Step 2. Creating a Filesystem

Next, create a filesystem on the new partition. In this example, we’ll use `EXT4`:

```shell
mkfs.ext4 /dev/sdb1
```

The filesystem is now ready.

#### Step 3. Mounting the Disk

To start using the disk, mount it to a directory. Each disk should have its own mount point.

For example, if you later add another disk (`sdc`), it should be mounted to a different directory.

Create a mount directory:

```shell
mkdir /mnt/disk2
```

Mount the disk:

```shell
mount -o barrier=0 /dev/sdb1 /mnt/disk2
```

You can now store files in `/mnt/disk2`, and they will be written to the new disk.

#### Step 4. Adding an Entry to /etc/fstab

To make the mount persistent after a reboot, add an entry to `/etc/fstab`.

You can reference the disk by its device name (e.g. `sdb1`), but this name may change if disks are reattached or other disks are removed. Using a UUID is recommended, as it is unique and stable.

To find the UUID, run:

```shell
lsblk -o NAME,UUID
```

Example output:

```shell
sda    
└─sda1 fcafbb78-fd6c-4083-82d8-3c06bd6ad4b1
sdb    
└─sdb1 534c6694-d2b0-4867-843b-b8a934bf0e5d
vda    041E-4E90
```

In this case, the UUID of our disk is `534c6694-d2b0-4867-843b-b8a934bf0e5d`.

Edit `/etc/fstab`:

```shell
nano /etc/fstab
```

Add the following line (replace the UUID with your own):

```shell
UUID=<disk-uuid> /mnt/disk2 ext4 defaults 0 2
```

## Resizing the Disk

We recommend creating a server backup before resizing disks.

You can only **increase** the disk’s size. Decreasing the size is not possible as it can seriously damage the file system.

### Main Disk

To resize your main disk, simply change your server plan:

1.  Go to the **Plan** tab.
2.  Click **Select plan**. 
3.  Select a plan with the sufficient disk size.
4.  Click **Save and reboot** to apply the changes.
5.  Confirm the action.
6.  Partition the disk, if necessary, following the steps below.

### Partitioning the Main Disk

> [!NOTE]
> This partioning is only needed if you have previously partitioned the disk yourself and now it has **two or more logical partitions**. In all other cases, the disk will be repartitioned automatically after you resize it in the dashboard.

**Step 1.** Boot the server [in the recovery mode](https://hostman.com/docs/cloud-servers/boot-mode/).

**Step 2.** Go to the **Console** tab and enter the following command to find out the disk name:

```shell
lsblk
```

Example output:

```shell
NAME    MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda       8:0    0   30G  0 disk 
├─sda1    8:1    0   10G  0 part /
├─sda2    8:2    0   4G  0 part 
├─sda14   8:14   0    4M  0 part 
├─sda15   8:15   0  106M  0 part /boot/efi
└─sda16 259:0    0  913M  0 part /boot
vda     253:0    0    1M  1 disk
```

In this example, `sda` is the system disk. On older servers, it may be called `vda`.

**Step 3**. Use the `parted` utiluty, using the system disk name:

```shell
parted /dev/sda
```

Execute the `print` command.

On the first run, you can receive the message:

```shell
Warning: Not all of the space available to /dev/sda appears to be used, you can fix the GPT to use all of the space (an extra 31457280 blocks) or continue
with the current setting? 
Fix/Ignore?
```

In this case, enter:

```shell
Fix
```

This will update the GPT table and allow to use all free disk space.

In the output of the `print` command, you will see the list of partitions.

![7ed673b6 A2a5 4f0b A475 087f9c353782.png](https://content.hostman.com/assets/e7cf86a2-2b14-4c3c-a5c0-6fece0044185.png?width=1018&height=366)

-   If you want to extend the last partition so it takes all the free space on the disk, go to **step 4a**.
    
-   If you want to create a new partition, proceed to **step 4b**.
    

We do not cover in this article the cases when you need to create several new partitions, but you can find those guides online.

If at this point you need to delete a partition, you can do it with the `rm` command, specifying the partition number, for example:

```shell
rm <partition_number>
```

**Step 4.** Partition the disk.

**Step 4a**. To extend the last partition, run the `resizepart` command, specifying the desired partition number and size. If you enter `100%`, the partition will take up all available space on the disk.     

```shell
resizepart <partition_number> 100%
```

Next:

-   -   Run `print` to check the result.
        
    -   Enter `q` to exit the partitioning program.
        
    -   Proceed to **Step 5**.
        

**Step 4b**. To create a new partition in a free disk space, run the `mkpart` command, specifying the partition type (`primary` or `extended`), its number and size. If you enter `100%`, the partition will take up all available space on the disk.     

```shell
mkpart primary <partition_number> 100%
```

Next:

-   -   Enter `yes` when prompted to confirm the new partition size.
        
    -   Run `print` to check the result.
        
    -   Enter `q` to exit the partitioning program.
        
    -   Create a file system in the new partition with the command below, specifying the partition name.
        

```shell
mkfs.ext4 /dev/sda3
```

**Step 5**. Check for errors and correct the file system structure. 

To do this, run the `e2fsck` command in the console, specifying the name of the partition from the **Step 4** (`/dev/sda2`, `/dev/sda3`, etc.):

```shell
e2fsck -yf /dev/sda2
```

![10e9e2a0 F362 4314 Be34 65e4bec2eecd](https://content.hostman.com/assets/d3755bcf-579b-4742-a847-a4a8c15707d1.png?width=1083&height=200)

**Step 6**. Resize the file system, specifying the partition name:

```shell
resize2fs /dev/sda2
```

![82049b53 F718 48ac 907b 81e7ddca35d1](https://content.hostman.com/assets/ace6bda6-207d-4dc6-bbd2-bb02e4486bd7.png?width=963&height=104)

**Step 7**. Check the file system after expansion.

Mount the partition that was modified (`/dev/sda2`, `/dev/sda3`, etc.):

```shell
mount /dev/sda2 /mnt
```

Check that the size was successfully changed:

```shell
df -h
```

![7dc701d2 2ddc 447f B8c7 F40f5f1ea16d](https://content.hostman.com/assets/dce45fd5-21ec-4c16-ac09-413cf5388d24.png?width=775&height=261)

If the disk size has remained the same, we recommend going back to **Step 1** and repeating the procedure once again.

If the disk size has changed, unmount the system disk:

```shell
umount /mnt
```

**Step 8**. Boot the server in the standard mode.

-   Go to the **Access** tab.
-   Click **Change** in the **OS boot mode** section.
-   Select **Standard mode**.
-   Click **Save and reboot**.

### Additional Disk

To change the size of an additional disk:

1.  Go to the **Plan** tab.
2.  Hover over the disk and click on the cog icon.
3.  Select new disk size.
4.  Click **Edit and restart**.
5.  Partion the disk following the steps below.

### Partitioning an Additional Disk

> [!NOTE]
> Before resizing, create a backup to prevent data loss in case of unexpected issues.

Run the following command to verify the new device size:

```shell
lsblk
```

Example output:

```shell
NAME    MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda       8:0    0   25G  0 disk
├─sda1    8:1    0 24.9G  0 part /
├─sda14   8:14   0    4M  0 part
└─sda15   8:15   0  106M  0 part /boot/efi
sdb       8:16   0   20G  0 disk
└─sdb1    8:17   0   10G  0 part
vda     252:0    0    1M  1 disk
```

In this example, the `sdb` device has been increased to 20G, but the `sdb1` partition is still 10G. Therefore, you need to repartition the disk and extend the filesystem.

#### Before repartitioning

If the disk is mounted via `/etc/fstab`, comment out the corresponding entry. Open the file:

```shell
nano /etc/fstab
```

Find the line corresponding to `/dev/sdb1` (or its UUID) and add `#` at the beginning of the line to comment it out. This prevents automatic mounting.

Before unmounting, check which processes are using the disk:

```shell
lsof /mnt/disk2
```

If the command returns no output, the disk is safe to unmount. If there are active processes, stop them or terminate the associated applications.

Unmount the disk:

```shell
sudo umount -l /mnt/disk2
```

#### Disk repartitioning

Start `fdisk` to edit the disk:

```shell
fdisk /dev/sdb
```

Delete the existing partition (without affecting the data). Enter `d` to delete the partition. If the disk has only one partition, as in this example, it will be selected automatically.

Create a new partition by entering:

-   Enter `n` to create a new partition
-   Select the same partition type (for example, `p` for primary)
-   Set the starting sector to the same value as before (the default is correct)
-   Set the ending sector to use the maximum available size (default)

When prompted:

```shell
Partition #1 contains a ext4 signature.
Do you want to remove the signature? [Y]es/[N]o:
```

Enter `N` to preserve the existing data.

Enter `w` to write the changes.

After exiting `fdisk`, run the following command to update the partition table in the system:

```shell
partprobe /dev/sdb
```

This updates the partition table in the kernel so the system recognizes the changes without requiring a reboot. If the operation is successful, no output will be displayed.

Run the command again:

```shell
lsblk
```

Verify that the partition has been updated and now uses the full available size.

```shell
NAME    MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda       8:0    0   25G  0 disk
├─sda1    8:1    0 24.9G  0 part /
├─sda14   8:14   0    4M  0 part
└─sda15   8:15   0  106M  0 part /boot/efi
sdb       8:16   0   20G  0 disk
└─sdb1    8:17   0   20G  0 part
vda     252:0    0    1M  1 disk
```

#### Extending the filesystem

After updating the partition, extend the filesystem to use the new space. For an EXT4 filesystem, run the following commands.

Check the filesystem:

```shell
e2fsck -f /dev/sdb1
```

Resize the filesystem:

```shell
resize2fs /dev/sdb1
```

After that, mount the disk again and uncomment the entry in `/etc/fstab`:

```shell
mount -o barrier=0 /dev/sdb1 /mnt/disk2
```

Verify that the new size is available:

```shell
df -h
```

Example output:

```shell
Filesystem      Size  Used Avail Use% Mounted on
tmpfs            96M  728K   96M   1% /run
/dev/sda1        25G  2.6G   22G  11% /
tmpfs           479M     0  479M   0% /dev/shm
tmpfs           5.0M     0  5.0M   0% /run/lock
/dev/sda15      105M  6.1M   99M   6% /boot/efi
tmpfs            96M     0   96M   0% /run/user/0
/dev/sdb1        20G   24K   19G   1% /mnt/disk2
```

The disk is now fully ready for use.

## Deleting Disks

1.  Go to the **Plan** tab.
2.  Hover over the disk and click on the bin icon.
3.  Confirm deleting the disk.

You also need to delete the disk from the operating system by removing the entry from the `/etc/fstab` file.

### Edit the /etc/fstab file

If the server has only one additional disk:

1.  Open the file:
    

```shell
nano /etc/fstab
```

2.  Delete or comment out the disk entry:
    

![Group 1321314175](https://content.hostman.com/assets/72b94fe0-18ef-4342-b685-bdca07ce23b7.png?width=928&height=580)

2.  Save changes (Ctrl + X, then Y and Enter).
    

If there are several additional disks on the server and the one you are deleting is not the last one:

1.  Open the file:
    

```shell
nano /etc/fstab
```

2.  Delete or comment out the disk entry:
    

![Group 1321314177](https://content.hostman.com/assets/48ca718e-7465-4af7-8f8f-43cbe17141ee.png?width=928&height=580)

3.  Check the disk names on your system, for example with the `lsblk` command. They should have moved one step up. Say, you had additional disks `vdc` and `vdd`. Then after deleting the `vdc` disk, you should see the following:
    

![Group 1321314178](https://content.hostman.com/assets/f3f65ee3-bd33-444a-ac84-8d4fcda40519.png?width=496&height=239)

This is actually your third disk (`vdd`), which has been mounted to the `/mnt/disk3` directory.

4.  Mount the disk to the same directory, specifying its updated name (in our case, `vdc1`):
    

```shell
mount -o barrier=0 /dev/vdc1 /mnt/disk3
```

5.  Edit the `/etc/fstab` file with the updated data:

```shell
nano /etc/fstab
```

![Group 1321314179](https://content.hostman.com/assets/b9a0d75b-8614-42c4-9349-5ea1e5be9305.png?width=923&height=579)

6.  Reboot the server.

## CPU and RAM

To change the CPU and RAM parameters of your server, change the server plan:

1.  Go to the **Plan** tab.
2.  Click **Select plan**. 
3.  Select a plan with the required parameters.
4.  Click **Save and reboot** to apply the changes.
5.  Confirm the action.

# Network Settings

Source: https://hostman.com/docs/cloud-servers/network/

You can manage the [server](https://hostman.com/cloud-server/)’s network settings in the **Network** tab.

## Private networks

You can add, transfer and remove servers from [private networks](https://hostman.com/docs/vpc/). 

**To add the server to a private network:**

1.  Go to **Cloud Servers** and click on the server.
    
2.  In the **Network** tab, click **Configure** next to **Private network**.
    
3.  Select an existing network or the **Add network** option to create a new one.
    
4.  Click **Transfer**.
    

Moving the server to another network will take some time; normally, moving 10 GB takes about one minute.

During the transfer, the server will be on and then rebooted when the transfer is complete. Total downtime will be 5-10 minutes.

The server’s public IP address may be changed.

**To remove the server from the private network:**

1.  Go to **Cloud Servers** and click on the server.
    
2.  In the **Network** tab, click **Configure** next to **Private network**.
    
3.  Click **Exclude from private network** and confirm.
    

## Traffic Routing Rules

If the server is added to a VPC, you can manage the [traffic routing rules](https://hostman.com/docs/vpc/nat/#traffic-routing-rules).

1.  Go to **Cloud Servers** and click on the server.
    
2.  In the **Network** tab, click **Configure** next to **Traffic routing rules (NAT)**.
    

![Image6](https://content.hostman.com/assets/8e64522a-d3f2-455f-b4b3-58b98980a05b?width=1495&height=694)

3.  Select a new routing rule and save the changes.
    

![Image3](https://content.hostman.com/assets/c926131f-5b18-4a46-8750-d28e8e33f05d?width=1490&height=763)

# Automatically Blocked Ports

Source: https://hostman.com/docs/cloud-servers/blocked-ports/

To prevent abuse, we automatically block certain network ports when a new server is created. 

This helps protect the infrastructure from being misused for spam, DDoS attacks, or unauthorized access.

We block the following ports by default:

-   **25, 465, 587, 2525**: email-related ports that are commonly used for sending spam;
-   **3389, 389, 53413**: ports commonly exploited for attacks (e.g., DDoS, credential theft, backdoors).

You can check which ports are blocked on your server via the server **Dashboard**. 

![Image1](https://content.hostman.com/assets/eb6e5160-de7e-4c76-8850-e3e7f34967b8.png?width=1520&height=1524)

> [!NOTE]
> The list reflects only those ports blocked by Hostman automatically; if you manually blocked specific ports on your server, they won’t be displayed on the dashboard.

If you're using your server for legitimate purposes and need access to one of the blocked ports, contact our support team via the chat in your dashboard—we’ll review your request and lift the restriction if appropriate.

### Blocked Ports FAQ

#### What port does SMTP use?

SMTP commonly uses ports 25, 465, and 587, as well as the alternate port 2525. 

#### What is the SMTP port number for encrypted email?

The standard SMTP encrypted port is 587, which supports STARTTLS. Ports 465 and 2525 are used for implicit SSL/TLS encryption. 

If you're unsure whether to use SMTP port 587 vs 25, select port 587 if you need to send email from a client application with login authentication.

#### Dashboard doesn’t show any blocked SMTP ports but I cannot send email from my server. Why?

You may have blocked the ports manually. You can test SMTP using the command line tools like `telnet`:

```shell
telnet <server IP address> <port number>
```

For example:

```shell
telnet 166.1.227.100 587
```

You can also use the hostname instead of the IP address:

```shell
telnet yourdomain.com 587
```

If the port is blocked, the connection will fail. 

#### Can I open the SMTP ports 25, 465, 587, 2525 on my server?

Yes, if you are using the server for legitimate purposes, contact our support team and request unblocking.

#### SMTP ports on my server are open, but email still isn't being sent. What could be the issue?

You may have configured your SMTP server incorrectly. 

You can run an SMTP server check using external tools such as [smtper.net](https://www.smtper.net/), [gmass.co](https://www.gmass.co/smtp-test), etc. There are many others, you can easily find them on the web.

They allow you to quickly check SMTP configuration online and verify authentication, encryption, and delivery settings.

#### What are ports 3389, 389, and 53413, and why are they blocked by default?

Port **3389** is used for Remote Desktop Protocol (RDP), which is often targeted in brute-force and credential-theft attacks. 

Port **389** is typically used for LDAP (Lightweight Directory Access Protocol). It's a known target for enumeration and exploitation attacks, especially when not properly secured.

Port **53413** is rarely used for legitimate services but is often reported as being used by malware or for creating hidden remote access (backdoors).

# Web Console

Source: https://hostman.com/docs/cloud-servers/web-console/

Console, or terminal, is a traditional method for managing Linux systems.

You enter commands into the terminal to be executed on the server and immediately see the result. All Linux distributions, FreeBSD and many others work this way. 

SSH clients (programs for working with the SSH protocol) exist for every operating system and are often built-in. On Linux or MacOS, you can use Terminal; on Windows, Windows PowerShell or PuTTY.

To [connect to a Hostman server via SSH](https://hostman.com/docs/cloud-servers/connect-to-server/) from the terminal on your machine, the server must have an Internet connection and SSH connections allowed. If for some reason Internet access on the cloud server is terminated or limited, you can use the web console in the Hostman dashboard.

![B35aa99a 1432 4b51 93b9 E16f38f1a835](https://content.hostman.com/assets/f30ec1a2-de66-4568-af73-cc183ece2f9b.png?width=1558&height=1150)

To connect as the `root` user, you need to use the login `root` and your root password, which can be copied from the server **Dashboard**:

![89814368 E667 4aef Bdc9 9d0206066c65](https://content.hostman.com/assets/3ba25fc2-6dea-47d9-a3b3-d74ebdd38666.png?width=1565&height=1200)

If you created an additional user on the server, you can also log in using its username and password.

## Serial Console

For Linux servers, the dashboard provides two types of console access: **serial console** and **VNC**.

![464dc621 2dc4 4e98 93b0 81cc582f81b6](https://content.hostman.com/assets/53be46d4-57bc-4ae9-8b2b-f250f084d7cb.png?width=1552&height=869)

We recommend using the **serial console**. In most cases, it is more convenient than VNC.

The serial console is enabled by default for all servers created after April 4, 2024. If your server was created earlier, the dashboard will display a hint with a command that you need to execute on the server to enable serial console support.

Like VNC, the serial console operates independently of the public network and SSH configuration and allows access to the server even in emergency situations.

However, compared to VNC, the serial console has several advantages:

-   Starts instantly.
-   Consumes fewer resources than VNC.
-   Supports the `Ctrl + Shift + C` and `Ctrl + Shift + V` keyboard shortcuts for convenient copying and pasting of commands.
-   Supports mouse interaction: you can select text in the terminal and copy or paste text using the right-click context menu.
-   Supports scrolling within the terminal.
-   Allows increasing or decreasing the font size using `Ctrl + +` and `Ctrl + −`.
-   Allows enabling syntax highlighting with a single command, which you can copy from the hint in the dashboard.

![1869d733 43dc 420b 8008 5b3faefa7c3b](https://content.hostman.com/assets/cdec4a09-0d5a-4378-96a9-e5eba8edd45f.png?width=1550&height=869)

## Logging In

To log into your server:

1.  Copy the root password from the **Dashboard** tab.
2.  Open the **Console** tab.
3.  If you are using the serial console, press **Enter**.
4.  Enter the username `root` and press **Enter**.
5.  Paste the password using Ctrl + Shift + V, wait a couple of seconds, and then press **Enter**.

## Pasting from Clipboard

The console supports pasting from the clipboard. You can copy passwords or commands and paste them into the console using `Ctrl + Shift + V`.

When pasting from the clipboard, a short delay may occur. After pasting a password, wait a couple of seconds before confirming it by pressing **Enter**.

## Full-Screen Mode

For convenience, you can expand the console to full screen:

![7e7b1326 655b 4f92 A787 E795cb4e3c48](https://content.hostman.com/assets/cace53de-bec8-43d9-b9be-bb80c65bce47.png?width=1547&height=866)

# Root Password Reset

Source: https://hostman.com/docs/cloud-servers/root-password-reset/

The easiest way to reset your [cloud server](https://hostman.com/cloud-server/)'s root password is through your Hostman dashboard.

> [!NOTE]
> You can also change the password [directly in the server's settings](https://hostman.com/docs/cloud-servers/administration/root-password-reset/) when connected via SSH. Note that in this case the root password you can copy in the dashboard will no longer work.

To reset the root password:

1.  Click on the lock icon on the server's page.
    

![Image2](https://content.hostman.com/assets/947cba5d-8470-4b18-a595-da199aa0369b?width=1477&height=1161)

2.  In the popup window click **Change password** to confirm password reset.
    

The new password will be immediately available on the **Dashboard**.

You can also reset the password in the **Access** tab:

![Image3](https://content.hostman.com/assets/96d06f22-e763-416f-9959-2c96ee5b2d3d?width=1482&height=781)

Click **Change** and then confirm resetting the password.

# SSH Keys

Source: https://hostman.com/docs/cloud-servers/ssh-keys/

You can use SSH keys to securely connect to [cloud servers](https://hostman.com/cloud-server/). For your convenience, it is possible to save the SSH keys in the dashboard and later use them when creating new cloud servers.

## Create SSH Keys

You can create SSH keys on your local machine [following our guide](https://hostman.com/docs/cloud-servers/administration/configure-ssh-keys/). When the keys are created, copy the public key to the server. You can do it manually via SSH or using the dashboard, as described below.

## Add an SSH Key to a New Server

When creating a new server, in the **Authorization** section, click **Add new key**. Select one of the existing SSH keys or add a new one.

The SSH key will be automatically added to the server and the dashboard so you can reuse it later.

![81678b4a B999 4e2f A991 Dcbd0f7cc8fe](https://content.hostman.com/assets/054609f4-baac-4c65-80ba-39ddca984b9f.png?width=1440&height=862)

## Add an SSH Key to an Existing Server

If the server already exist, you can still add SSH keys to it via the Hostman dashboard. 

1.  Go to **Cloud Servers** and click on the server you need.
2.  In the **Access** tab, click **Change** next to **SSH keys**. 
    

![D1d9a561 A9bc 42bb 975e 9cd1978537af](https://content.hostman.com/assets/646190cf-a709-499b-839e-89b3eb6259b7.png?width=1529&height=868)

3.  Select one of the SSH keys already saved in the dashboard or add a new one.
    

The key will be added to the server automatically in a couple of minutes without rebooting.

## Add an SSH Key to Your Hostman Dashboard

You can also add SSH keys to the dashboard without linking them to any server yet.

1.  Go to **Cloud Servers** → **SSH Keys** and click **Add SSH** key.
    

![1e497316 A923 4e15 873a 9f6e23b2e89f](https://content.hostman.com/assets/00ff0ac8-9bbf-4cf9-9c1e-07f1b26d4985.png?width=1514&height=807)

2.  Paste the key and enter its name to be displayed in the dashboard.
    
3.  (Optional) Mark the key as default, if necessary. The default SSH key will be automatically added to new servers. 
    
4.  Click **Add**.
    

![726f9387 0fd2 4b50 A50e 806bd0ae30df](https://content.hostman.com/assets/f1223238-762b-43cf-8170-16e228029a5f.png?width=1352&height=867)

The key will be displayed in the list of SSH keys and will be available for selection when creating a new server and reinstalling the OS.

## Set a Default SSH Key

If you want to use a specific SSH key for all new servers, mark it as default. You can do it when creating a key in the in **Cloud Servers** → **SSH Keys** section:

![2d64e145 8951 4506 8f5f 6888cc0af425](https://content.hostman.com/assets/b4b410a9-33fc-40d7-a903-8048ffd09a63.png?width=1352&height=867)

Or when the key already exists. Go to **Cloud Servers** → **SSH Keys** and check the **Select this SSH key by default when creating a new server** box. 

![Hostman Laptop 2026 08 20 13 25](https://content.hostman.com/assets/c869947f-1f0a-4a0b-9b36-54f0b9f519f3.png?width=1581&height=869)

## Delete an SSH Key

To delete an SSH key:

1.  Go to the **Cloud Servers** → **SSH Keys** section.
2.  Click on the three dots and select **Delete SSH key**.

![Ef340ee0 5037 4ac6 9b7c 8eda8c3f586d](https://content.hostman.com/assets/94252a6c-bb7e-41a3-bc30-3b41eb5ddb36.png?width=1539&height=722)

# Reboot a Server

Source: https://hostman.com/docs/cloud-servers/reboot/

You can reboot your cloud servers from the dashboard.

## How to Reboot a Server

1.  Go to **Cloud Servers** and click on the server you want to reboot.
2.  Click the **Reboot** icon.

![7aba90ff 56f3 43b9 A0b5 1d6ad54b2dfd](https://content.hostman.com/assets/c7f3c11e-1337-4420-ae1e-175d2e7d8f26.png?width=1557&height=780)

3.  Select the reboot type: **OS Reboot** or **Server Reboot**.
    

![9636a354 C1b5 4a0a 8502 A91ff903106f](https://content.hostman.com/assets/c48193c5-fb4b-420e-aa31-3619b4e375cd.png?width=1569&height=784)

4.  Click **Reboot** to confirm.
    

## Soft Reboot (OS Reboot)

A soft reboot is initiated by the operating system. The server receives a restart command and shuts down gracefully:

-   running services and applications are stopped;
-   open files and network connections are closed;
-   pending data is written to disk.

After the shutdown process completes, the system starts again.

This is equivalent to running commands such as `reboot` or `shutdown -r now` in the terminal.

**In most cases, a soft reboot is the recommended option**. For example, use it after changing configuration, updating the system or kernel, or as a first step when troubleshooting minor server issues.

## Hard Reboot (Server Reboot)

A hard reboot is a forced restart performed at the infrastructure level. It does not involve the operating system and is similar to turning the server’s power off and back on.

During a hard reboot, running processes are terminated immediately, and any data stored in memory may be lost. When the system starts again, it may run a filesystem check.

Use a hard reboot only if the server is unresponsive, for example:

-   the server has frozen;
-   SSH access is unavailable;
-   a soft reboot does not resolve the issue;
-   the system no longer responds to commands.

# Boot Mode

Source: https://hostman.com/docs/cloud-servers/boot-mode/

To perform certain operations on the [cloud server](https://hostman.com/cloud-server/), such as resetting the root password from within the OS or partitioning the disk, you will need to boot the OS in a specific mode. 

To change the system boot mode:

1.  Go to **Cloud Servers** and click on the server.
    
2.  In the **Access** tab, click **Change** next to **OS boot mode**:
    

![Image5](https://content.hostman.com/assets/9058c214-2a16-4f8a-b930-6820731869f9?width=1504&height=974)

3.  Select the boot mode and click **Save and Reboot**.
    

![Image8](https://content.hostman.com/assets/83cc5cfd-f5f2-4918-b892-dda46b28eae2?width=1472&height=759)

# Reinstall Operating System

Source: https://hostman.com/docs/cloud-servers/os-reinstall/

Whenever necessary, you can easily reinstall your [server](https://hostman.com/cloud-server/)'s operating system using the tools in your Hostman dashboard.

> [!NOTE]
> Please note that reinstalling the operating system will delete all data on the disk.

The backups in the dashboard will not be deleted. Reinstalling will not affect the private network settings.

To reinstall the operating system:

1.  Go to the **Plan** tab and click **Reinstall**.

![Image1](https://content.hostman.com/assets/7a7fe37f-e63b-4c8c-b6e6-aecf37ee9873?width=1475&height=992)

2.  Select which software to install: 

-   -   a clean operating system,
        
    -   a pre-configured image with a specific application from the **Marketplace** tab,
        
    -   a custom image that can be chosen or uploaded in the **Custom image** tab. 
        

![Image2](https://content.hostman.com/assets/73418093-023b-4030-8da9-da14dcb01da1?width=1455&height=1123)

3.  (Optional) In the **Authorization** section can select an SSH key from those saved in the dashboard or add a new one.
4.  Add [a cloud-init script](https://hostman.com/docs/cloud-servers/cloud-init/) if necessary.
5.  Click **Reinstall**.
6.  Confirm the deletion of all disk data, after which the system will be reinstalled.

# Performance Monitoring

Source: https://hostman.com/docs/cloud-servers/stats/

Monitoring server performance provides important insights into the system operation and helps you determine whether your [cloud server](https://hostman.com/cloud-server/) is working as it should or something requires your attention

On the **Dashboard** tab of each server you will find graphs of the processor, memory and bandwidth usage, as well as data on disk utilization.

With these graphs, you can analyze the state of your server at a glance and evaluate if server parameters need tweaking (say, increasing the number of CPU cores or the disk size).

## Bandwidth

Here, you can monitor inbound and outbound traffic.

To view the exact value of the indicators at the required moment, move the cursor over the desired point on the chart.

![Image5](https://content.hostman.com/assets/9fab58ab-cd6b-4076-95d3-d573f4f0bc70?width=722&height=375)

## CPU

The CPU graph tells you the percentage of all the processor cores utilization. For each core, the maximum value is 100%, so the maximum value on the graph can be 200%, 400%, and so on, depending on the number of processor cores.

To view the exact value of the indicators at the required moment, move the cursor over the desired point on the chart.

![Image1](https://content.hostman.com/assets/37ca3639-fcba-4248-b16f-7c1189fd5faa?width=721&height=374)

## Memory

For RAM, we display two graphs: one displays the amount of memory used by applications, and the second the total amount of memory used, occupied by both applications and the operating system for disk caching.

When you hover your cursor over a point on the graph, you can see the exact value.

![Image3](https://content.hostman.com/assets/b19364c7-eba6-439b-9549-d0e56a47901b?width=728&height=378)

By clicking on a specific chart view (Used or Used with cache), you can disable and re-enable displaying it:

![Image4](https://content.hostman.com/assets/3330b9fb-229c-4b88-9d39-2980f377a3ac?width=727&height=374)

## Disk

For the disk, we monitor the disk space , as well as the load on the disk.

### Disk space

When there is little free space on a disk, it negatively affects the server performance, which is why you should monitor the disk space usage.

The **Dashboard** displays the current state of the main (system) disk. Data is updated once an hour.

![Image2](https://content.hostman.com/assets/28944a8d-b5c6-4d33-9211-a69b7140e889?width=369&height=378)

### Disk Load

The graph allows you to monitor the read and write operations performance.

![Image6](https://content.hostman.com/assets/09729a00-5791-4082-98ab-ab1d6ea6a9d9?width=721&height=379)

# Backups

Source: https://hostman.com/docs/cloud-servers/backups/

Backup is an important part of keeping your [cloud server](https://hostman.com/cloud-server/) running. If data is accidentally deleted, or operation is disrupted after updates or changes, you can always restore the contents of the disk using the backups. 

If you reinstall the server, the previously made backups are still kept in your Hostman dashboard, so you can restore the server with them.

> [!NOTE]
> Keep in mind that the copies created in the Hostman dashboard do not protect against all possible problems. Should there be a serious software or hardware failure or if the server is accidentally deleted, it will be impossible to restore the data.
>
> We recommend creating remote copies to ensure complete safety of your data.

In the Hostman dashboard you can create both backups and snapshots (recovery points).

## Backups

You can create and delete backups, restore data from them, and also manage automatic backups in the **Backups** tab.

#### Price

The cost of backups depends on the disk size: $0.07 per 1 GB.

You pay for storing the copies, not creating them. Even if you no longer create new backups, the existing ones will be billed until they are deleted from the dashboard.

### Create Backups

To create a new backup:

1.  Go to the **Cloud Servers** section and click on the server.
2.  In the **Backups** tab, click **Create backup**.
3.  Select the disk to back up.
4.  Confirm the action.

![B9a9bd6e D006 4ce1 9ec0 B4d2f49fd256](https://content.hostman.com/assets/1fc106ff-5823-4e75-bd38-5f0e2c0128a6.png?width=1562&height=840)

Depending on the disk size and the load on the Hostman backup system at the moment, the process can take from a couple of seconds to several minutes. Once it completes, a copy will appear in the dashboard.

Please note that you cannot create a backup if a snapshot has been created on the server.

### Automatic Backups

To set up automatic backups:

1.  Go to the **Cloud Servers** section and click on the server.
2.  In the **Backups** tab, click **Settings**.

![Cf4b93dc 1c1f 49bb 84a7 3574d9b69495](https://content.hostman.com/assets/e52bd434-1dc4-4b90-84bd-d844ce419d10.png?width=1562&height=840)

3.  Enable automatic backups and set the parameters:
    -   the frequency of backup creation (daily / weekly / monthly);
    -   the number of copies to keep;
    -   the start date for creating backups automatically.
4.  Save your settings.

![Ed1d6b1f 7839 478c 91a8 7c47ad1b0558](https://content.hostman.com/assets/410cb760-2ea3-40e7-b63c-0fe8ef32aa71.png?width=1560&height=795)

### Restore Data From Backup

We recommend turning the server off before performing this operation.

1.  Go to the **Cloud Servers** section and click on the server.
2.  Go to the **Backups** tab.
3.  To fully restore the disk (restore all data):
    -   Hover over the backup and click on the **Restore** option.
    -   Confirm the action.

![77e9f4d8 93ff 45fc 8842 55dc76672662](https://content.hostman.com/assets/827232b3-76db-48e7-94fc-8a00b1c0bfed.png?width=1563&height=844)

Restoring will take some time, depending on the size of the backup.

4.  To restore the data partially:
    -   Hover over the backup and click on the **Mount** option.
    -   Confirm the action.

![8915f769 8be6 46bc A34b C3cc505feeb0](https://content.hostman.com/assets/a7e512c5-897d-4d02-a4c6-c6589b6955c1.png?width=1563&height=844)

After this, the disk will appear in the system, but will be available in the read-only mode. You need to mount this disk inside the operating system following the steps below.

Note that:

-   Mounting the backup takes some time, so you will not see the disk immediately after mounting it in the Hostman panel. Give it a few minutes.
    
-   Before unmounting the backup in the dashboard first unmount it within the operating system.
    

### Mount Backups

Mounting a backup means connecting a disk inside the operating system. 

In the examples below, we use the disk name `sdb`. You should replace it with the actual disk name on your system. You can check disk names with:

```shell
lsblk
```

Example output:

```shell
NAME    MAJ:MIN RM  SIZE RO TYPE MOUNTPOINTS
sda       8:0    0   25G  0 disk
├─sda1    8:1    0 24.9G  0 part /
├─sda14   8:14   0    4M  0 part
└─sda15   8:15   0  106M  0 part
sdb       8:16   0   25G  1 disk
├─sdb1    8:17   0 24.9G  1 part
├─sdb14   8:30   0    4M  1 part
└─sdb15   8:31   0  106M  1 part
vda     252:0    0    1M  1 disk
```

Here, the `sda` is the system disk, and `sdb` is our backup.

1.  Connect to your server via SSH or use the console in the Hostman panel.
    
2.  Mount the disk using the `mount` command:
    

```shell
mount /dev/sdb1 /mnt
```

### Unmount Backups

To unmount the disk:

1.  Unmount it within the operating system using the `umount` command:

```shell
umount /dev/sdb1
```

2.  Click on the **Unmount** button in the Hostman dashboard.
3.  Confirm the action.

![D6720d74 9bdd 4ec9 A0d3 64fa5b66a326](https://content.hostman.com/assets/cc77bacd-808f-4167-809c-75fbebbc81e8.png?width=1577&height=844)

It is not possible to unmount a backup in the dashboard as long as it is still mounted within the operating system.

### Download the Backup

You can download the backup to your device.

1.  Go to the **Cloud Servers** section and click on the server.
2.  Open the **Backups** tab.
3.  Hover over the backup and click on the **Mount** option.
4.  Confirm the action.
5.  Mount the backup in the OS [following the guide above](https://hostman.com/docs/cloud-servers/backups/#mount-backups).
6.  Connect to the server via SFTP, for example using Filezilla, using the details:
    -   Host: Your server's IP address
    -   Login: root
    -   Password: root user password
    -   Port: 22
7.  Save the backup folder to your computer and [unmount the backup](https://hostman.com/docs/cloud-servers/backups/#unmount-backups).

### Delete Backups

To delete a backup: 

1.  Go to the **Cloud Servers** section and click on the server.
2.  Open the **Backups** tab.
3.  Click on the the three dots next to the backup and select **Delete backup**.
4.  Confirm the action.

Deleting backups is not possible if a snapshot is created on the server.

## Snapshots

Snapshots (recovery points) are another backup method. With this method, you basically take a snapshot of the current state of the server, which is very easy to roll back to.

On Hostman, snapshots are free.

Unlike a backup, a snapshot is created for the entire server as a whole, and not for a separate disk, and is also created and restored instantly, while creating and restoring data from a backup can take up to 30 minutes or more.

Snapshots are convenient to use when you need to quickly and safely test something: create a snapshot before making changes, and then, if necessary, return the server to its previous state.

However, a backup is a more reliable way of long-term data storage, since it is a complete copy of the disk, stored on a separate server.

If a snapshot is created, the following actions will not be available for the server:

-   adding, removing or resizing a disk;
-   creating or deleting backups;
-   creating a server image;
-   reinstalling the operating system;
-   server cloning.

To perform them, you will first need to delete the snapshot.

### Create a Snapshot

The server must be on.

1.  Go to the **Cloud Servers** section and click on the server.
2.  In the **Backups** tab, click **Create snapshot**.
3.  Confirm the action.

The snapshot will appear in the dashboard in a couple of seconds.

You can only create one snapshot for one server. It is stored for 7 days, after which it is automatically deleted.

### Restore Data From the Snapshot

To restore the server using the snapshot:

1.  Go to the **Cloud Servers** section and click on the server.
2.  Go to the **Backup** tab.
3.  Click **Restore** in the **System snapshot** block.
4.  Confirm the action. 

![85ce725d 8d93 495d 86dc 687cf6c76686](https://content.hostman.com/assets/3e623af5-ecc8-4327-8c39-d7ec9f5d25d9.png?width=1566&height=940)

The server will be rolled back to the state at the time the snapshot was created, and the snapshot itself will be deleted.

Any changes that were made after the snapshot was created will be permanently lost.

### Delete a Snapshot

Snapshots are deleted automatically after 7 days but you can also delete the snapshot manually.

1.  Go to the **Cloud Servers** section and click on the server.
2.  Go to the **Backup** tab.
3.  Click **Delete** in the **System snapshot** block.
4.  Confirm the action. 

![25cd3f56 Be1d 41d2 84cd 9f2c96bf1a69](https://content.hostman.com/assets/b747e557-3b64-45c2-9a71-fd72135abb59.png?width=1566&height=940)

## General Backup Guidelines

For more efficient work with the cloud servers, we recommend following these guidelines when creating backups and snapshots:

-   Create backups regularly depending on how often the data changes on the server. In the case of online stores, large web portals, and online media, it is recommended to back up daily. In the case of a small website, it is enough to make a backup once a month.
    
-   Create a backup or snapshot before major updates in the files or databases. Make sure the update went smoothly and then delete the backup.
    
-   Make a backup after the major changes to ensure you have the most recent copy of your data.

# Server Cloning

Source: https://hostman.com/docs/cloud-servers/cloning/

Using the cloning option, you can quickly create a copy of a [cloud server](https://hostman.com/cloud-server/). Cloning will create a server with the same parameters (processor, memory, disk size), as well as copy all the data.

Cloning does not affect the original server's operation in any way.

Before cloning, make sure that:

-   The server is on.
-   There is no server snapshot. If the snapshot is created, you will need to delete it before cloning the server.
-   You have enough funds in the account balance to pay for the new server. 

To clone a server:

1.  Go to the **Cloud Servers** section and click on the server you want to clone.
2.  Click on the copy icon on the server page:

![Dd6fd2fc 610d 42af A9be 24ff73fdbbaf](https://content.hostman.com/assets/ecef0920-2a76-4443-8ee0-4b62c229faed.png?width=1536&height=788)

3.  Set up network parameters for the new server:

-   -   Specify whether the server requires a public IP address. You can create a new IP, select one of the existing IP addresses, or choose **No externel IP**.
    -   Specify whether to add the server to a private network. You can create a new network, select an existing one, or choose **Without a private network**.

4.  If necessary, specify a custom server name and add a comment.
5.  Click **Clone**.

![05008330 3ff3 4e31 9b64 771839e0a502](https://content.hostman.com/assets/a3b6112e-7718-4b3d-b2d0-ec8eb59aa7bd.png?width=1561&height=1155)

Cloning will only take a few minutes. 

After completing the process, you can immediately start working with the new server. You can find the new server IP address as well as the login and password in the new server’s **Dashboard**. 

Please note that the new server will have a different IP address. Therefore, you may need to update some internal server settings as they will be copied "as is". For example, if a static IP was configured on the previous server, this setting will be transferred to the new server with the same (old) IP address. In this case, you will need to reconfigure [using this guide](https://hostman.com/docs/cloud-servers/administration/configure-static-ip/).

# Server Images

Source: https://hostman.com/docs/cloud-servers/images/

Using server images, you can:

-   Upload your images to the dashboard.
-   Create images of your Hostman servers.
-   Deploy new servers using images in the dashboard.
-   Download the images and then deploy servers at other cloud providers.

You can also use images as a way to backup data. When you create an image of a Hostman server, it creates a complete copy of your cloud server  in `Qcow2` format, including all operating system settings, software and all server content. 

Unlike backups and snapshots created in the Hostman panel, images are stored separately from the server and will not be lost when the server is deleted. You can always access them through the **Images** section.

> [!NOTE]
> Images are available for servers located in Amsterdam and Frankfurt

Images are provided for free.

If the balance runs out and the account is blocked, images will be deleted in 7 days.

## Create an Image

> [!NOTE]
> You cannot create a server image if there is a snapshot created for the server.

1.  Go to the **Cloud Servers** section and click on the server.
2.  In the **Images** tab, click on the plus sign next to the disk.

![03ba4fea D35e 4d92 8e49 Dfd530216147](https://content.hostman.com/assets/a8344243-3798-406c-b676-7f9a52433ba2.png?width=1532&height=802)

3.  Enter an image name and comment, if necessary, to make it easier to navigate the list of images.
4.  Click **Create**.

The image will be created in a couple of minutes.

You can find all the images created on the account in the **Cloud Servers** → **Custom Images** section of your dashboard.

![Cloud Servers 2026 08 20 11 47](https://content.hostman.com/assets/c47f17cf-03a9-4509-a32b-8f197939b1e8.png?width=1575&height=829)

## Download an Image

To download an image:

1.  Go to the **Cloud Servers** → **[Custom Images](https://hostman.com/my/images)** section.
2.  Hover over the image and click **Download**. The image file will be downloaded to your device.

![123](https://content.hostman.com/assets/31a6b40d-fffc-41c6-b378-73ddb3f19c14.png?width=1543&height=867)

You can also download an image from the server’s page.

1.  Go to the **Cloud Servers** section.
2.  Click on the server.
3.  In the **Images** tab, click on the **Created images: N** link.

![Fbc3f115 2e41 4544 8d4b 864103341d10](https://content.hostman.com/assets/49178071-c0d8-4ee6-9f0f-0ab19549b981.png?width=1534&height=812)

4.  Hover over the image and click **Download**. The file will begin downloading to your device.
    

![61b30a74 B3da 439b 99e6 043135745a08](https://content.hostman.com/assets/7f4820aa-0891-4d55-8c62-5bce889844a8.png?width=1555&height=656)

## **Move an Image to Another Region**

You can move an image to a different location to create servers from it there.

1.  Make sure [you have created an image](https://hostman.com/docs/cloud-servers/images/#create-an-image) of the server you need.
    
2.  Go to **Cloud Servers** → **[Custom Images](https://hostman.com/my/images)**.
    
3.  Click the three dots next to the image and select **Edit region**.
    

![Cloud Servers 2026 07 02 12 35](https://content.hostman.com/assets/2cc7c886-a9d7-4017-88d7-5d392ae67ff0.png?width=1565&height=824)

4.  Choose the new location and click **Save**.
    

The image will be moved to the selected region within a few minutes. After that, you can [create servers from this image](https://hostman.com/docs/cloud-servers/images/#create-a-server-from-an-image) in the new location.

## Upload a Custom Image

You can upload an image from your computer or via URL. 

The image should be in one of the following formats: `iso`, `vmdk`, `vhd`, `vhdx`, `vdi`, `raw`, `img` and `qcow2`.

The maximum file size is 500 GB.

To upload a custom image to your dashboard:

1.  Go to the **Cloud Servers** → **[Custom Images](https://hostman.com/my/images)** section.
2.  Click **Upload image**.
3.  Select the region where you want to store the image.
4.  Select the OS so that the logo displays later in the **Images** section, for easier navigation.
5.  Select the image file on your machine or enter an URL.
6.  Click **Upload**.

![B26ad3c7 E57a 4dfc Bca0 Ed7627b63272](https://content.hostman.com/assets/252ee5a1-8dfd-4b70-a1f1-64445fcbd3c3.png?width=1547&height=868)

You can also upload images when creating a new server or reinstalling an existing one:

![Create Server 2026 08 20 11 43](https://content.hostman.com/assets/f5018f37-1217-4c75-8dd5-234097739fa4.png?width=753&height=542)

## Create a Server From an Image

To create a server using an image:

1.  Go to **Cloud Servers** and click **Create Server**.
    
2.  In the **Custom images** tab, select an existing image or click **Add new image** to upload a new one.
    

![Create Server 2026 08 20 11 43](https://content.hostman.com/assets/f5018f37-1217-4c75-8dd5-234097739fa4.png?width=753&height=542)

3.  Complete creating the server.
    

You can also create servers from the **Cloud Servers** → **[Custom Images](https://hostman.com/my/images)** section. Hover over the image and click **Create server from image**.

![A202ea24 3933 4b4b B71c Da4737bad5c3](https://content.hostman.com/assets/d31b845c-7892-4975-840d-e5bb658127ed.png?width=1545&height=866)

You will be redirected to the server creation page to complete the order. 

## Reinstall a Server From an Image

You can reinstall a server using any of the images available on your account.

1.  Go to the **Cloud Servers** section and click on the server.
2.  In the **Plan** tab, click **Reinstall**. 
3.  Select the image in the **Custom image** tab.

![3fc72d81 21c0 47b2 847d 1991924c9ce1](https://content.hostman.com/assets/a25c0c15-5c8e-4a5a-91f0-379f6c0b9f0f.png?width=1545&height=716)

## Upload an Image to Google Drive

You can upload your server images from the Hostman dashboard to your Google Drive.

> [!NOTE]
> Before proceeding, make sure that you have enough free space on your Google Drive, otherwise, the upload will be interrupted mid-stream.
>
> Google Drive has a daily traffic limit of 750 GB. Once you reach this limit, you won't be able to upload anything to Google Drive for the rest of the day.

1.  Go to the **Cloud Servers** → **[Custom Images](https://hostman.com/my/images)** section.
    
2.  Hover over the image and click **Upload to external storage**.
    

![4839e06e 8446 45c9 9071 E8df4684e61e](https://content.hostman.com/assets/54d0d355-ebe3-4463-bccf-36c15efdc0b3.png?width=1543&height=866)

3.  Change the file name if necessary and click **Upload**.
    
4.  Select the Google account and confirm the download.
    
5.  The first time you try to upload an image, you will need to allow access to your Google Drive. Simply follow the suggested steps. Afterwards the download will start.
    

You can also upload an image to Google Drive from a server’s page.

1.  Go to **Cloud Servers** and click on the server.
2.  In the **Images** tab, click on the **Created images: N** link
3.  Hover over the image and click **Upload to external drive**.

The remaining steps are the same as when uploading from the **Images** section.

# Action History

Source: https://hostman.com/docs/cloud-servers/history/

You can monitor operations performed on a [cloud server](https://hostman.com/cloud-server/) in the **History** tab.

![9bbb6faa 6c44 41ed 9639 26395afd8038](https://content.hostman.com/assets/f913ca30-8faf-4d6e-991b-c1506969582c?width=1540&height=1152)

You can search by events, select specific services and dates. 

The **History** tab logs all operations performed, such as:

-   Turning the server on and off
-   Rebooting
-   Reinstalling the OS
-   Changing configuration (processor cores, RAM, drives)
-   Adding and deleting IP addresses
-   Creating, deleting, mounting, and unmounting backups
-   Blocking the server due to insufficient funds or violations of the terms and conditions

The account owner can also see which user performed each action. By clicking on the user name you can move on to the user settings to update permissions.

# Delete Servers

Source: https://hostman.com/docs/cloud-servers/delete-server/

To delete a [cloud server](https://hostman.com/cloud-server/):

1.  Go to the **Cloud Servers** section
2.  Click on the three dots and select the **Delete server** option.

![Image3](https://content.hostman.com/assets/5e0534a4-a9db-4477-9b65-3ffc58cf4699?width=1482&height=785)

3.  Confirm the deletion by entering the server’s name. 
4.  Press **Delete cloud server**.

![Image2](https://content.hostman.com/assets/010ae6fb-6f8d-4713-8231-d5f5fca2adec?width=1480&height=792)

You can also delete from the server’s page:

1.  Go to the **Cloud Servers** section.
2.  Click on the server you want to delete.
3.  Click on the bin icon at the top right.

![Image1](https://content.hostman.com/assets/2fdd0a8b-41ca-46d0-b78f-2358edc8377c?width=1481&height=795)

4.  Confirm the deletion by entering the server’s name. 
5.  Press **Delete cloud server**.

![Image2](https://content.hostman.com/assets/010ae6fb-6f8d-4713-8231-d5f5fca2adec?width=1480&height=792)

# Server Administration

Source: https://hostman.com/docs/cloud-servers/administration/

This section contains practical guides for working inside your server’s operating system. Here you’ll find step-by-step instructions for creating users, configuring the network, installing software, and setting up services and applications.

Use these articles when you need to manage or customize the server environment directly, beyond the Hostman dashboard.

-   [Create Users](https://hostman.com/docs/cloud-servers/administration/create-users/)
-   [Reset the root Password](https://hostman.com/docs/cloud-servers/administration/root-password-reset/)
-   [Configure SSH Keys](https://hostman.com/docs/cloud-servers/administration/configure-ssh-keys/)
-   [Configure a Static IP Address](https://hostman.com/docs/cloud-servers/administration/configure-static-ip/)
-   [Configure a Server Image](https://hostman.com/docs/cloud-servers/administration/configure-a-server-image/)
-   [Install the QEMU Guest Agent](https://hostman.com/docs/cloud-servers/administration/install-qemu-guest-agent/)
-   [Deploy Hermes Agent](https://hostman.com/docs/cloud-servers/administration/hermes-agent/)
-   [Deploy OpenClaw](https://hostman.com/docs/cloud-servers/administration/deploying-openclaw/)

# Create Users

Source: https://hostman.com/docs/cloud-servers/administration/create-users/

For data safety and security reasons, it is not recommended to work with a Linux system under `root` as it may lead to accidental but irreversible file or system damage.

In this guide, we will describe how to create users in **Ubuntu**/**Debian** and **CentOS** and assign them `sudo` privileges. With `sudo`, the user will be able to perform operations as `root` when necessary.

## Creating Users with sudo Privileges

> [!NOTE]
> To create a user without `sudo` privileges, simply follow the first three steps.

### Step 1. Create a New User

You can do this with the `adduser` command:

```shell
adduser <username>
```

For example:

```shell
adduser hostman
```

This command will automatically add the new user to a group with the same name and create a home directory.

### Step 2. Set the User Password

-   In **Ubuntu** or **Debian**, you will be prompted to enter the new user's password. You will need to enter it twice.
-   In **CentOS**, run the following command:

```shell
passwd <username>
```

For example:

```shell
passwd hostman
```

Enter the password twice.

### Step 3. Enter User Information

-   In **Ubuntu** / **Debian**, the system will propmt you to enter additional information about the user (name, phone number, etc.). You can enter these data or press Enter to use the default (empty) values. Next, press `Y` to confirm.
-   In **CentOS**, you need to run a specific command if you wish to enter additional information:

```shell
chfn <username>
```

Enter the necessary data.

At this point, you have successfully created a user without `sudo` privileges. You can switch to the new user with:

```bash
su - <username>
```

### Step 4. Assign sudo Privileges

To assign `sudo` privileges, you need to add the user to the `sudo` group.

-   **Ubuntu / Debian:**

```shell
usermod -aG sudo <username>
```

-   **CentOS:**

```shell
usermod -aG wheel <username>
```

### Step 5. Check the New User

Switch to the new user:

```shell
su - username
```

Enter the user's password when prompted.

Now, try to execute any command that requires `sudo`. For example, you can list the `/root` directory content which a normal user cannot access.

```shell
sudo ls -la /root
```

If the system lists the `/root` direcory, your new user is all set. 

### Step 6. (Optional) Disable root Login

This step is optional but for extra security, you can disable remote access for the `root` superuser. This ensures that users will always need to connect under their own accounts, allowing you to track actions on the server, see who made specific changes, and so on.

1.  Open the `/etc/ssh/sshd_config` file:

```shell
sudo nano /etc/ssh/sshd_config
```

2.  Find the line `PermitRootLogin` and change its current value to:

```shell
PermitRootLogin no
```

3.  Exit the editor, saving your changes (use the key combination Ctrl + X, then Y, then Enter).
4.  Restart the SSH service with the commands below.

**On Ubuntu / Debian:**

```shell
sudo service ssh restart
```

**On CentOS:**

```shell
sudo service sshd restart
```

## Commands for Managing Users

Use `id` to get user information:

```shell
id <username>
```

The output will look similar to this:

```shell
uid=1000(<username>) gid=1000(<username>) groups=1000(<username>),27(sudo)
```

To changer the user password, run:

```shell
passwd <username>
```

To list all existing users:

```shell
cat /etc/passwd
```

To list all users currently logged in the system, use:

```shell
w
```

To delete a user, run:

```shell
deluser <username>
```

# Reset the root Password

Source: https://hostman.com/docs/cloud-servers/administration/root-password-reset/

The easiest way to reset the root user password is [through the Hostman dashboard](https://hostman.com/docs/cloud-servers/root-password-reset/). This method works even if the old password is lost, as you do not need to enter it.

However, you can also reset the password directly in the operating system, using the guide below.

> [!NOTE]
> Note that If you change the password via SSH, the root password you can copy in the dashboard will no longer work.

## If You Know the root Password

If you know the current password for the root user, you can change it as follows.

1.  Connect to the server via SSH as `root` using the current password.
2.  Execute the command:

```shell
passwd
```

3.  The system will ask for the new password twice. Enter it.

Done, the password is changed. You can now log in as `root` using the new password.

## If the root Password is Unknown

If you don't know the current root password, you can reset it and set a new one by booting the server from the recovery disk.

1.  Boot the system [from the recovery disk](https://hostman.com/docs/cloud-servers/boot-mode/).
2.  In the **Console** in the dashboard.
3.  Mount the `root` partition. Its name may vary: `sda1` or `vda1`. First, try:

```shell
mount -o rw /dev/sda1 /mnt
```

If you receive the error:

```shell
mount: /mnt: fsconfig system call failed: /dev/sda1: Can't lookup blockdev.
```

run:

```shell
mount -o rw /dev/vda1 /mnt
```

Then execute:

```shell
chroot /mnt /bin/bash
passwd root
```

4.  The system will ask for the new `root` password twice. Enter it.

If the password is changed successfully, you will see a confirmation message, such as: `passwd: all authentication tokens updated successfully` or `password updated successfully`.

5.  Press CTRL + D to exit `chroot`.
6.  Unmount the disk with the command:

```shell
umount /mnt
```

6.  Remount the root file system in read-only mode, using vda1 or sda1, depending on what worked in the Step 3:

```shell
mount -o ro /dev/sda1 /mnt
```

7.  Reboot the server [in standard mode](https://hostman.com/docs/cloud-servers/boot-mode/) via the dashboard.

Now you will be able to connect to the server as `root` using the new password.

# Configure SSH Keys

Source: https://hostman.com/docs/cloud-servers/administration/configure-ssh-keys/

In this article, we will look at how to create SSH keys on devices with different operating systems and how to copy them to a server for SSH connections.

## Create SSH Keys

Follow these steps to create an SSH key pair on your local machine.

> [!NOTE]
> This guide will work for Linux, MacOS, and the newer versions of Windows 10 starting from 1809, which have a built-in SSH client. If you have an older version of Windows, you will need to use an SSH client such as PuTTY.

1.  Launch a terminal or Windows PowerShell on your computer and run the command:
    

```shell
ssh-keygen
```

2.  You will see a similar message:
    

```shell
Generating public/private rsa key pair.
```

Enter file in which to save the key (`/home/user/.ssh/id_rsa`):

3.  Press Enter to save the key to the default directory.
    
4.  Next, set a passphrase or press Enter to leave it blank. Using a passphrase increases security, but you will have to enter it every time you log in to the server.
    

That’s it; the keys are created. 

The private key will be stored on your machine, while the public key should be copied to the server. This can be done manually [as described below](https://hostman.com/docs/cloud-servers/administration/configure-ssh-keys/#copy-an-ssh-key-to-the-server) or, more conveniently, by [using your Hostman dashboard](https://hostman.com/docs/cloud-servers/ssh-keys/#add-an-ssh-key-to-a-new-server).

## Create SSH Keys with PuTTY

Old Windows versions don’t have OpenSSH, so you'll need a special program, PuTTYgen. You can download the `puttygen.exe` distribution from the official PuTTY website.

1.  Launch the program.
    
2.  Select **RSA** in the **Type of key** **to generate** block and click **Generate**.
    
3.  Move your mouse randomly in the space below the loading line to generate random values.
    
4.  After the key is created, you can set the Key passphrase. This is optional; you can leave the line blank. If you choose to set a passphrase, please note that you will need to enter it each time you log in using the key.
    
5.  Next, save the created keys by clicking on the **Save public key** and **Save private key** buttons, for example, as `id_rsa.pub` and `mykey.ppk`.
    
6.  Also, copy and save the contents of the **Public key for pasting...** window as a text file, as you will need them later when copying the SSH key to the server or the Hostman panel.
    

## Copy an SSH Key to the Server

> [!NOTE]
> You can also transfer the public SSH key to the server [via the Hostman dashboard](https://hostman.com/docs/cloud-servers/ssh-keys/#add-an-ssh-key-to-a-new-server).

Run the following command on your local computer's terminal. In place of user, enter a username created on the server, and in place of server, enter the server IP address.

### Linux and MacOS

```shell
ssh-copy-id user@server
```

For example:

```shell
ssh-copy-id root@38.62.228.244
```

### Windows

```shell
type $env:USERPROFILE\.ssh\id_rsa.pub | ssh user@server "cat >> .ssh/authorized_keys"
```

For example:

```shell
type $env:USERPROFILE\.ssh\id_rsa.pub | ssh root@38.62.228.244 "cat >> .ssh/authorized_keys"
```

As a result, the contents of the `id_rsa.pub` file with the public key will be copied to the `~/.ssh/authorized_keys` file on the server, and in the future, you will be able to establish a connection to the server using the command:

```shell
ssh user@server
```

For example:

```shell
ssh root@38.62.228.244
```

### Windows (with PuTTY)

On older Windows versions, you will need the `pageant` utility to copy the SSH key to your server. You can download the `pageant.exe` distribution from the official PuTTY website.

1.  Connect to the server via SSH via Putty and run the command to create a file on the server to store keys:
    

```shell
chmod 0700 ~/.ssh
touch ~/.ssh/authorized_keys
chmod 0644 ~/.ssh/authorized_keys
```

2.  Open the file:
    

```shell
nano ~/.ssh/authorized_keys
```

3.  Paste the text public key, previously copied from the PuTTYgen window, into it and save the file.
    
4.  Launch `pageant`. Its icon will appear in the tray. Right-click on it and select **Add Key**.
    
5.  Enter the path to the private key `mykey.ppk`, saved earlier, and click **Open**. If you added a passphrase when creating the key, pageant will ask for it at this stage.
    

To check that key authorization works, run PuTTY, connect to your server, and enter your login. If everything is configured correctly, you will see an output similar to this in the console window:

```shell
Authenticating with public key "rsa-key-20151220" from agent
```

## Disable Password Authentication

You can disable password authentication on your server to ensure that it can only be accessed with the SSH key. To do this, you need to edit the `/etc/ssh/sshd_config` file on your server.

1.  Connect to the server via SSH and open the file with the command:
    

```shell
sudo nano /etc/ssh/sshd_config
```

2.  Find the `PasswordAuthentication` line in it and replace its value with:
    

```shell
PasswordAuthentication no
```

3.  Save the changes, then restart the SSH service:  
    

```shell
sudo service ssh restart
```

## Troubleshooting

If you are unable to connect using an SSH key, check the SSH logs on the server:

```shell
sudo journalctl -u ssh
```

If the logs contain the following entry:

```shell
userauth_pubkey: key type ssh-rsa not in PubkeyAcceptedAlgorithms [preauth]
```

this indicates that support for `ssh-rsa` (RSA with SHA-1) is disabled on the server. In this case, you can resolve the issue using one of the following approaches.

**Option 1 (Recommended)**. Generate a new key using a more secure algorithm.

For a stronger RSA key:

```shell
ssh-keygen -t rsa -b 4096 -o -a 100
```

Alternatively, generate an Ed25519 key:

```shell
ssh-keygen -t ed25519
```

After generating the key, upload the new public key to the server.

**Option 2.** Allow authentication using `ssh-rsa` by updating the SSH daemon configuration.

Add the following line to `/etc/ssh/sshd_config.d/enable_rsa_keys.conf`:

```shell
HostKeyAlgorithms +ssh-rsa
PubkeyAcceptedKeyTypes +ssh-rsa
```

Then restart the SSH service:

```shell
sudo systemctl restart sshd
```

# Configure a Static IP Address

Source: https://hostman.com/docs/cloud-servers/administration/configure-static-ip/

If your [server](https://hostman.com/cloud-server/) sometimes becomes unavailable without any apparent reason, the issue might be related to the server losing its IP address. 

By default, the server is assigned a dynamic IP address, which has a lease time. Before this lease time expires, the server must request a new IP address, and then DHCP will automatically assign the same IP. 

However, some Linux distributions request the IP address slightly later than needed (after the lease time has expired), causing the IP address to be temporarily lost.

To fix this issue, you need to configure a static IP on your server.

## Required Parameters

To follow the steps below, you will need the parameters: 

-   **IP Address**: This is the IP address of your server. We will use `192.0.2.70` as an example. You need to replace it with your actual IP address.
    
-   **Subnet Mask**: Add `/24` to your IP address. In our example, it will be `192.0.2.70/24`.
    
-   **Gateway**: This is the first address in the network; you just need to change the last number of the IP address to `1`. In our example: `192.0.2.1`.
    
-   **Interface**: The interface name will vary depending on the distribution. For example, it could be `eth0` or `ens3`. You can check it using the command `ip addr`.
    

To continue with the guide, connect to your server via SSH as root. 

## Ubuntu 18.04 and later, Debian 12

1.  Create the `/etc/netplan/99-ipv4.yaml` file using a text editor:

```shell
nano /etc/netplan/99-ipv4.yaml
```

2.  Update it with the following directives, removing the previous ones. Replace `192.0.2.70/24` and `192.0.2.1` with your actual IP address and gateway:

```yml
network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: false
      addresses:
        - "192.0.2.70/24"
      routes:
        - to: "0.0.0.0/0"
          via: "192.0.2.1"
      nameservers:
        addresses:
          - "1.1.1.1"
          - "1.0.0.1"
```

3.  Restrict read permissions on this file to everyone except `root`:

```shell
chmod 600 /etc/netplan/99-ipv4.yaml
```

### Disabling Previous Settings in Ubuntu

1.  Check the `/etc/netplan/` directory; there may be other interface settings that could conflict with yours.

```shell
ls -a /etc/netplan/
```

2.  Normally, it will have the `50-cloud-init.yaml` file. Rename it so it doesn't end with `.yaml`:

```shell
mv /etc/netplan/50-cloud-init.yaml /etc/netplan/50-cloud-init.yaml-backup-$(date +"%Y%m%d")
```

3.  Do the same to other files in the `/etc/netplan/`, except `99-ipv4.yaml`, if it exists.
4.  To prevent `cloud-init` from creating new files, make the following file:

```shell
nano /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
```

5.  And add this line to it:

```shell
network: {config: disabled}
```

### Listening on an Address in Ubuntu

After rebooting the server, an address might not be added in time when other services want to listen on it. Therefore, we allow binding to addresses that are not yet available on the interface.

1.  Open the `/etc/sysctl.conf` file:

```shell
nano /etc/sysctl.conf
```

2.  Add this line to it:

```shell
net.ipv4.ip_nonlocal_bind = 1
```

3.  Reload the `sysctl` configuration:

```shell
sysctl -p /etc/sysctl.conf
```

### Applying Settings in Ubuntu

1.  Apply the netplan configuration:

```shell
netplan --debug apply
```

2.  Check that the address has been added to the interface:

```shell
ip addr
```

Reboot the server and verify that the address is working correctly.

### Ubuntu Configuration Example

For Ubuntu network settings, all configuration files are located in `/etc/netplan/`. You can see your final configuration by running:

```shell
netplan get
```

Here is an example of the configuration if you follow each step in this guide to configure the `166.1.227.252` IP address:

```yml
network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      addresses:
      - "166.1.227.252/24"
      nameservers:
        addresses:
        - "1.1.1.1"
        - "1.0.0.1"
      dhcp4: false
      routes:
      - to: "0.0.0.0/0"
        via: "166.1.227.1"
```

## Debian 9, 10, 11

> [!NOTE]
> Starting from Debian 12, Debian uses Netplan for network configuration. If you have Debian 12, use the [previous section](https://hostman.com/docs/cloud-servers/configure-static-ip/#ubuntu-18-04-and-later) of this article.

1.  Open the `/etc/network/interfaces` file using a text editor:

```shell
nano /etc/network/interfaces
```

2.  Comment out or remove the current `eth0` settings: 

```shell
#allow-hotplug eth0
#iface eth0 inet dhcp
```

3.  Add the following lines, replacing `192.0.2.70/24` and `192.0.2.1` with your actual IP address and gateway:

```shell
auto eth0
allow-hotplug eth0
iface eth0 inet static
	address 192.0.2.70/24
gateway 192.0.2.1
```

### Disabling Previous Settings in Debian

1.  Check if the directory `/etc/network/interfaces.d/` has other interface settings that could conflict with yours.

```shell
ls -a /etc/network/interfaces.d/
```

2.  Normally, it will have the `50-cloud-init` file. Move it to another directory:

```shell
mv /etc/network/interfaces.d/50-cloud-init /root/50-cloud-init-backup-$(date +"%Y%m%d")
```

3.  To prevent `cloud-init` from adding new files, create the `99-disable-network-config.cfg` file:

```shell
nano /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
```

4.  And add the following line to it:

```shell
network: {config: disabled}
```

### Listening on an Address in Debian

After rebooting the server, an address might not be added in time when other services want to listen on it. Therefore, we allow binding to addresses that are not yet available on the interface.

1.  Open the /etc/sysctl.conf file:

```shell
nano /etc/sysctl.conf
```

2.  Add the following line to it:

```shell
net.ipv4.ip_nonlocal_bind = 1
```

3.  Reload the `sysctl` configuration:

```shell
sysctl -p /etc/sysctl.conf
```

### Applying Settings in Debian

1.  Restart the networking service:

```shell
systemctl restart networking.service
```

2.  Check that the address has been added to the interface:

```shell
ip addr
```

The IP address you configured should be listed under the `inet` section of the `eth0` block.

Reboot the server and verify that the address is working correctly.

### Debian Configuration Example

Debian uses the `/etc/network/interfaces` file for network settings.

Here is an example of the configuration if you follow each step in this guide to configure the `166.1.227.252` IP address:

```
auto lo
iface lo inet loopback

auto eth0
allow-hotplug eth0
iface eth0 inet static
    address 166.1.227.252/24
    gateway 166.1.227.1
```

## CentOS 7 and later

CentOS uses `NetworkManager` for network configurations. Instead of editing configuration files, you can use the `nmcli` or `nmtui` utilities.

1.  Check the connection name:

```shell
nmcli connection show
```

You need the value from the `NAME` column — in our case, it is `ens3`. This name will be used in the following commands:

```shell
NAME  UUID                                  TYPE      DEVICE
ens3  xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx  ethernet  ens3
```

If your connection name differs, do not forget to replace `ens3` in the commands below with the correct connection name.

2.  Add the address to the connection:

```shell
nmcli connection modify ens3 ipv4.addresses 192.0.2.70/24
```

3.  Add the gateway:

```shell
nmcli connection modify ens3 ipv4.gateway 192.0.2.1
```

4.  Copy and execute these commands. They set DNS configurations and specify manual configuration:

```shell
nmcli connection modify ens3 ipv4.dns 1.1.1.1
nmcli connection modify ens3 +ipv4.dns 1.0.0.1
nmcli connection modify ens3 ipv4.method manual
```

### Disabling Previous Settings in CentOS

1.  Check the `/etc/sysconfig/network-scripts/` directory; there may be other interface settings that could conflict with yours. 

```shell
ls -a /etc/sysconfig/network-scripts/
```

2.  Normally, there will be an `ifcfg-ens3` file. Move the file to another directory, such as `/root/`:

```shell
mv /etc/sysconfig/network-scripts/ifcfg-ens3 /root/ifcfg-ens3-backup-$(date +"%Y%m%d")
```

3.  To preserve the changes after the server reboots, create the following file: 

```shell
nano /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
```

4.  And add this line to it:

```shell
network: {config: disabled}
```

### Listening on an Address in CentOS

After rebooting the server, an address might not be added in time when other services want to listen on it. Therefore, allow binding to addresses that are not yet available on the interface.

1.  Open the `/etc/sysctl.conf` file:

```shell
nano /etc/sysctl.conf
```

2.  Add the following line:

```shell
net.ipv4.ip_nonlocal_bind = 1
```

3.  Reload the `sysctl` configuration:

```shell
sysctl -p /etc/sysctl.conf
```

### Applying Settings in CentOS

1.  Restart the `NetworkManager` service:

```shell
systemctl restart NetworkManager.service
```

2.  Check that the addresses have been added to the interface:

```shell
ip addr
```

Reboot the server and verify that the addresses are working correctly.

### CentOS Configuration Example

In the latest versions of CentOS, NetworkManager saves its settings in the `/etc/NetworkManager/system-connections/` directory. 

Here is an example of the final configuration content in `/etc/NetworkManager/system-connections/` when configuring the `166.1.227.252` IP address with this guide:

```shell
[connection]
id=ens3
uuid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
type=ethernet
interface-name=ens3
timestamp=1719197216

[ethernet]

[ipv4]
address1=192.0.2.70/24,192.0.2.1
dns=1.1.1.1;1.0.0.1;
method=manual

[proxy]
```

# Configure a Server Image

Source: https://hostman.com/docs/cloud-servers/administration/configure-a-server-image/

Before creating a cloud server from a custom image, you should properly configure the image to ensure correct installation and full functionality of the dashboard.

Below are the checks and configurations you should perform to successfully create the server.

## Basic Configuration

### Partition Table

Check the disk partitioning scheme. We recommend using MBR or GPT; both are supported by most Linux distributions using tools like `fdisk`, `gdisk`, etc.

Example command:

```shell
gdisk -l /dev/vda
```

Example output:

```shell
GPT fdisk (gdisk) version 1.0.5
Partition table scan:
  MBR: MBR only
  BSD: not present
  APM: not present
  GPT: not present
```

If another partitioning scheme is used, you’ll need to recreate the image with the correct one.

### Disk Layout

If the disk contains a single root partition using the `ext3` or `ext4` file system, the system will automatically resize the filesystem during server creation to match the configured disk size.

For example, if the image block device is 10 GB and the server is created with a 15 GB disk, the block device and filesystem will expand to 15 GB.

> [!NOTE]
> Note: Resizing will not occur if LVM (Logical Volume Manager) is used.

### Bootloader

The virtual machines use SeaBIOS, so the OS must have a BIOS-compatible bootloader installed.

If a UEFI bootloader is installed, it must be removed and replaced with a BIOS-compatible one.

If using GRUB2, refer to its [installation guide](https://wiki.archlinux.org/title/GRUB).

### /etc/fstab Configuration

For stable booting, use UUID-based mounting in `/etc/fstab` for the root partition.

Example:

```shell
UUID=f19002a1-6e7a-45ac-91cd-24b7cc0e4cd9 / ext4 defaults 0 1
```

To get the UUID of a partition:

```shell
blkid
```

Example output:

```shell
/dev/vda1: UUID="f19002a1-6e7a-45ac-91cd-24b7cc0e4cd9" TYPE="ext4" PARTUUID="f7a1fae1-01"
/dev/loop0: TYPE="squashfs"
/dev/loop1: TYPE="squashfs"
/dev/loop2: TYPE="squashfs"
```

### Root User

A password for the `root` user will be generated when creating the server. Ensure that the root user exists (i.e., hasn't been manually removed).

### qemu-guest-agent

Make sure the `qemu-guest-agent` is installed and running. It is needed for operations such as backups from the dashboard.

Check its status:

-   Systemd:
    

```shell
systemctl status qemu-guest-agent.service
```

-   OpenRC / init.d:
    

```shell
/etc/init.d/qemu-guest-agent status
```

Or:

```shell
service qemu-guest-agent status
```

Install if missing:

-   Debian/Ubuntu:
    

```shell
apt-get install qemu-guest-agent
```

-   CentOS / RHEL:
    

```shell
yum install qemu-guest-agent
```

-   Alpine Linux:
    

```shell
apk add qemu-guest-agent
```

Enable on boot:

-   Systemd:
    

```shell
systemctl enable qemu-guest-agent.service
```

-   init.d:
    

```shell
chkconfig --add qemu-guest-agent
```

-   OpenRC:
    

```shell
rc-update add qemu-guest-agent
```

These configurations are enough for creating a cloud server from the image.

Other settings below are recommended for convenience and usability.

## Additional Settings

### Installing Zabbix

To collect server statistics, we use the Zabbix agent.

Install it using the following script:

```shell
wget -O - http://repo.hostman.com/zabbix-install.sh | bash
```

### Network Settings

Ensure network connectivity after the server boots.

Configure a DHCP client to automatically obtain an IP address.

Most systems have DHCP clients installed. We recommend using dhclient with the following config:

```bash
option rfc3442-classless-static-routes code 121 = array of unsigned integer 8;

send host-name = gethostname();
request subnet-mask, broadcast-address, time-offset, routers,
        domain-name, domain-name-servers, domain-search, host-name,
        netbios-name-servers, netbios-scope, interface-mtu,
        rfc3442-classless-static-routes, ntp-servers;

timeout 300;
```

### SSH Access

SSH is used to access the server. Make sure it is installed and enabled on boot.

Check status:

-   Systemd:
    

```shell
systemctl status ssh.service
```

-   OpenRC / init.d:
    

```shell
/etc/init.d/ssh status
```

Or:

```shell
service ssh status
```

Install if missing:

-   Debian/Ubuntu:
    

```shell
apt-get install openssh-server
```

-   CentOS / RHEL:
    

```shell
yum -y install openssh-server openssh-clients
```

-   Alpine Linux:
    

```shell
apk add openssh
```

Enable on boot:

-   Systemd:
    

```shell
systemctl enable ssh.service
```

-   init.d:
    

```shell
chkconfig --add ssh
```

-   OpenRC:
    

```shell
rc-update add sshd
```

Also, ensure your firewall allows access to port 22 (default SSH port).

### Disable Swap

It is recommended to disable swap.

Check if swap is active:

```shell
swapon --show
```

Example output:

```shell
NAME      TYPE SIZE USED PRIO
```

Disable swap:

```shell
swapoff -a
```

# Install the QEMU Guest Agent

Source: https://hostman.com/docs/cloud-servers/administration/install-qemu-guest-agent/

To fully manage your Hostman [server](https://hostman.com/cloud-server/) in the dashboard, you need to have the **QEMU Guest Agent** installed. 

If the QEMU agent is not installed or is disabled, some dashboard functionality will be unavailable, such as managing backups, snapshots, or SSH keys, resetting your root password, and others.

If you installed any software from the marketplace while creating the server, the QEMU guest agent will be installed automatically. Otherwise, you can install it manually by following this guide.

## Checking for QEMU Guest Agent

To check if the QEMU guest agent is installed on your server:

1.  Connect to the server via SSH.
2.  Run the following command:

```shell
systemctl status qemu-guest-agent
```

If you have a similar output, it means the guest agent is up and running:

![Powershell 25 Kh J1u Wr D](https://content.hostman.com/assets/586b2be6-f504-4ec1-ad72-60aef9615cb1.png?width=771&height=218)

If the output looks like this, it means the agent is not installed:

```shell
Unit qemu-guest-agent.service could not be found.
```

In this case, the agent is installed but disabled—you need to restart it:

```shell
Active: inactive (dead) since ...
```

## Restarting QEMU Guest Agent

If you've already installed the QEMU guest agent but some features of the dashboard are still unavailable, try restarting the agent. This will likely solve the issue.

1.  Connect to the server via SSH.
    
2.  Run the following command:
    

```shell
systemctl restart qemu-guest-agent.service
```

3.  Check that everything is working correctly with the following command:
    

```shell
systemctl status qemu-guest-agent.service
```

If everything is in order, the output will be as follows:

![Powershell 25 Kh J1u Wr D](https://content.hostman.com/assets/586b2be6-f504-4ec1-ad72-60aef9615cb1.png?width=771&height=218)

## Installing QEMU Guest Agent

To install the QEMU agent, connect to the server via SSH and run the appropriate commands for your operating system.

### Ubuntu 18.04 and higher

```shell
apt update && apt install qemu-guest-agent -y;
```

### CentOS Stream 9

```shell
yum install qemu-guest-agent
```

### Debian 8 and higher

```
apt update;
apt install qemu-guest-agent -y
```

# Deploy Hermes Agent

Source: https://hostman.com/docs/cloud-servers/administration/hermes-agent/

[Hermes Agent](https://hermes-agent.nousresearch.com/) is a self-hosted AI agent from Nous Research. It runs on your own server, works with files and tools, executes terminal commands, and keeps a history of your sessions. You interact with the agent through a text-based interface in the terminal.

Hostman provides a ready-to-use image with Hermes pre-installed. Once you've created a server, all that's left is to connect it to an AI agent or to AI Gateway.

## Creating a Server

1.  In the control panel, go to the [Cloud Servers](https://hostman.com/my/servers) section.
2.  Click **Create Server**.
3.  Choose a region for your server.
4.  On the **Image** step, open the **Marketplace** tab and select the **Hermes** image.

![Create Server 2026 08 03 17 25](https://content.hostman.com/assets/a4d4a512-d37a-4572-ad8b-6aa455e00b81.png?width=742&height=708)

5.  Choose a server configuration and adjust any other settings as needed (you can leave the defaults).
6.  Click **Create**.

Hermes and all the components it needs are installed automatically when the server is created.

## Choosing a Connection Method

You can connect Hermes to either an [AI agent](https://hostman.com/docs/ai-agents/) or to [AI Gateway](https://hostman.com/docs/ai-agents/ai-gateway/).

**If you connect to an AI agent**, you'll be able to use a [knowledge base](https://hostman.com/docs/ai-agents/manage-knowledge-bases/). In this case, Hermes works with a single model—whichever one is selected in the agent's settings. To switch models, change the model in the Hostman dashboard.

**If you connect to the AI Gateway**, you won't be able to use AI agent knowledge bases. However, you'll be able to choose any model available in AI Gateway and switch between models on the fly.

Before you start, gather the connection details you'll need:

#### For an AI agent

-   [Base URL of the agent](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url): shown in the agent’s **Dashboard**
-   [Access key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

If you haven't created an AI agent yet, [follow this guide](https://hostman.com/docs/ai-agents/manage-agents/create/).

![C424c212 63bf 4019 9219 44cb2787635c.png](https://content.hostman.com/assets/93474a51-a6e5-49d8-a2ed-1145439daf21.png?width=1560&height=1410)

_Agent's Base URL in the Dashboard_

#### For AI Gateway

-   Base URL: `https://ai-api.hostman.com/v1`
-   [AI Gateway API key](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key)

Note that AI Gateway uses its own separate keys, unrelated to AI agent keys.

## Setting Up the Connection

**Step 1. Connect to your server over SSH**

1.  Open a terminal: Terminal on macOS/Linux, PowerShell on Windows.
    
2.  Open the server's **Dashboard** tab and copy the command from **SSH connection**.
    

![Hermes 2026 08 03 17 32](https://content.hostman.com/assets/1a61bb6e-714a-49ed-9f4c-1f8ddfd5e972.png?width=1578&height=1152)

_SSH connection command in the Dashboard_

3.  Paste the command into your terminal and press **Enter**.
    

**Step 2. Confirm the connection (first time only)**

On your first connection, you'll see a prompt like this:

```shell
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

Type `yes` and press Enter.

Enter the root password from the **Dashboard** when prompted. The password won't be displayed as you type—this is normal terminal behavior.

![Hermes 2026 08 03 17 34](https://content.hostman.com/assets/8bc3fbb3-636f-4e9f-b7c7-278371bb9bdb.png?width=1577&height=1152)

_Server root password in the Dashboard_

**Step 3. Exit Hermes to access the server console**

The Hermes text interface opens automatically once you connect. 

To run the setup script in the next step, you need to return to the server console first.

To do this, type `/exit` and press **Enter**.

**Step 4. Run the setup script**

Run this command in the terminal:

```shell
curl -fsSL https://st.hostman.com/cloud-static/hostman-hermes-autoinstall.sh -o /tmp/hostman-hermes-autoinstall.sh && bash /tmp/hostman-hermes-autoinstall.sh
```

**Step 5. Enter your configuration details**

The script will prompt you for:

-   **Base URL**: The base URL of your AI agent or AI Gateway
-   **API Key**: The access key

**Step 6. Review and confirm**

After you enter these values, the script checks the connection and displays the resulting configuration.

Review the values. If everything looks correct, type `y` and press **Enter**.

The script will add the `ai-agent` provider and open the chat interface.

![Hql Y53 Nkti](https://content.hostman.com/assets/654341eb-16ea-4e94-8b08-c43e5b3905d2.png?width=1103&height=639)

_[Hermes Agent](https://hermes-agent.nousresearch.com/) interface in [Windows PowerShell](https://learn.microsoft.com/en-us/powershell/)_

## Selecting a Model in AI Gateway

This step is only needed if you're connecting through AI Gateway. When using an AI agent, Hermes always talks to the model selected in the agent's settings.

In the Hermes interface, run:

```shell
/model
```

This opens the model selection window. Choose the `ai-agent` provider, then select the model you want to use.

You can change the model at any time during your session using the same `/model` command.

## Working with Hermes

To manually launch the Hermes text interface, run:

```shell
hermes --tui
```

From this interface, you can send requests to the agent, view its responses, and track tool executions.

Useful commands:

| **Command** | **Action** |
| --- | --- |
| `/help` | Open the list of commands |
| `/model` | Select a model |
| `/sessions` | Switch between open sessions or start a new one |
| `/usage` | View token usage and context fill level |
| `/new` | Start a new conversation |
| `/details` | Show or hide tool call details |

To resume your last session after exiting, run:

```shell
hermes --tui --continue
```

To open a specific saved session by its ID or name, use:

```shell
hermes --tui --resume "<id_or_name>"
```

Key keyboard shortcuts:

| **Shortcut** | **Action** |
| --- | --- |
| `Enter` | Send a message |
| `Alt+Enter` or `Ctrl+J` | Add a new line |
| `Ctrl+C` | Cancel the current operation; pressing it again exits Hermes |
| `Ctrl+D` | Exit Hermes |

Once everything is set up, send the agent a test request to confirm it responds correctly. If you're using AI Gateway, select a model with `/model` first.

For other commands and interface features, see the [official Hermes documentation](https://hermes-agent.nousresearch.com/docs/user-guide/tui).

# Deploy OpenClaw

Source: https://hostman.com/docs/cloud-servers/administration/deploying-openclaw/

[OpenClaw](https://openclaw.ai/) is a self-hosted AI assistant that can be deployed on a cloud server. Unlike traditional chatbots, OpenClaw not only responds to requests but can also perform real actions: send messages, process data, work with files, and interact with external services.

You can interact with OpenClaw through messaging platforms, or directly via API or the command line.

## Creating a Server

To run OpenClaw, create a server with an appropriate configuration in the dashboard.

1.  Go to **Cloud Servers**.
2.  Click **Create Server**.
3.  Choose the region where the server will be deployed.
4.  In the next step, open the **Marketplace** tab and select the **OpenClaw** image.

![5ca847c9 3380 460b Beea A01f1ce99f03](https://content.hostman.com/assets/58773efc-d41d-4893-bb8f-50fe7a1bc9ad.png?width=743&height=479)

5.  Select the server configuration. We recommend the following specifications:
    

-   -   4 CPU cores
    -   8 GB RAM
    -   160 GB NVMe storage

6.  Configure the remaining parameters (you can leave them unchanged).
7.  Click **Create**.

## OpenClaw Basic Setup

After the server is created, complete the initial OpenClaw configuration.

Connect to the server via SSH. The connection details (IP address, username, password, or SSH key) are available in the server **Dashboard** tab.

![15182e5d F166 40cb Bbe1 F32fa7c27d2a](https://content.hostman.com/assets/25a104aa-4396-4792-a0b0-339392fa5187.png?width=1562&height=1521)

When you log in for the first time, the OpenClaw setup wizard starts automatically. If it does not start or was closed, you can launch it manually:

```shell
openclaw onboard
```

Then follow these steps:

1.  Review the disclaimer and accept the terms by selecting **Yes**.
2.  In **Onboarding** **mode**, choose **QuickStart**.
3.  In **Model/auth provider**:
    -   If you have an API key from an external provider, select that provider.
    -   If you're planning to use Hostman's AI agents, select **Skip for now**.
4.  In **Filter models** **by provider**, choose **All providers**.
5.  Leave **Default model** unchanged.
6.  At **Select channel (QuickStart)**, you can configure a messaging platform. See the [instructions below](https://hostman.com/docs/cloud-servers/administration/deploying-openclaw/#connecting-telegram) to connect Telegram at this point.
7.  At **Configure skills now?**, select **No**.
8.  At **Enable hooks?**, choose **Skip for now** (press Space, then Enter).
9.  At **How do you want to hatch your bot?**, select **Do this later**.

![6ed980ec 12a2 42b2 B6cf E8b92e9027fb.png](https://content.hostman.com/assets/0384f4fe-7489-43e7-8c7a-8bf9db0b8487.png?width=1502&height=1376)

_[OpenClaw](https://openclaw.ai/) setup wizard_

## Connecting to AI Agents

If you're planning to use [Hostman's AI agents](https://hostman.com/docs/ai-agents/), run the following command to launch the connection script:

```shell
curl -fsSL https://st.hostman.com/cloud-static/hostman-openclaw-autoinstall.sh -o /tmp/hostman-openclaw-autoinstall.sh && bash /tmp/hostman-openclaw-autoinstall.sh
```

The script will prompt you to enter:

-   [Agent's base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url)
-   [Agent's API key](https://hostman.com/docs/ai-agents/manage-agents/api-access-key/)

Confirm the values by pressing `Y`.

This launches the OpenClaw console interface. You can check that the connection works by sending a test message.

If you need to change these settings later, run the setup wizard again with:

```shell
openclaw onboard
```

To interact with OpenClaw from the terminal, use its text interface. Launch it with:

```shell
openclaw tui
```

This opens an interactive console where you can send messages to the agent, view its responses, and track its activity.

## Connecting Telegram

To interact with OpenClaw via Telegram, you need to create your own bot and obtain an API key. This can be done using the official Telegram bot `@BotFather`.

In Telegram:

1.  Open [@BotFather](https://t.me/BotFather) and start a conversation.
2.  Run the `/newbot` command.
3.  Enter a bot name (this will be displayed in chats).
4.  Enter a unique username that must end with bot (for example, `openclaw_hostman_bot`).

After completing these steps, BotFather will generate an API key. This key is required to integrate the Telegram bot with OpenClaw.

Return to the OpenClaw setup wizard. At **Select channel (QuickStart)**:

-   Choose **Telegram**
-   Paste the API key you received

Complete the setup and start a conversation with your bot by sending:

```shell
/start
```

The bot will reply with a pairing code.

On the server, run:

```shell
openclaw pairing approve telegram <code>
```

Replace `<code>` with the pairing code you received from the Telegram bot.

Once approved, the bot is ready to use. You can send commands and interact with the agent directly through Telegram.

## Web Interface

The web interface can be used to interact with the agent and manage its operation. Through it, you can communicate with the bot, check active sessions and their status, manage access tokens, and perform basic configuration. The interface is intended for administration and debugging and is not designed for public internet access.

![8e54273c 0fa2 4d32 Bd49 A631750ec42f](https://content.hostman.com/assets/43c23ed8-3b14-430b-bdd1-daccfb649b59.png?width=2934&height=1670)

_Chat section in the [OpenClaw](https://openclaw.ai/) web interface_

To access the web interface, run the following command after connecting to the server via SSH:

```shell
openclaw dashboard
```

You will receive output similar to:

```shell
🦞 OpenClaw 2026.2.3-1 (d84eb46) — I keep secrets like a vault... unless you print them in debug logs again.

Dashboard URL: http://127.0.0.1:18789/?token=c6aaee5ae1fd9a7925892f4738f37deb01d2bd13d0c11199
Copy to clipboard unavailable.
No GUI detected. Open from your computer:
ssh -N -L 18789:127.0.0.1:18789 root@147.45.148.206
Then open:
http://localhost:18789/
http://localhost:18789/?token=c6aaee5ae1fd9a7925892f4738f37deb01d2bd13d0c11199
Docs:
https://docs.openclaw.ai/gateway/remote
https://docs.openclaw.ai/web/control-ui
```

This command is used to generate a token. You will need the value from the `Dashboard URL` line.

By default, the web interface is available only locally on the server and is not accessible externally. For remote access, it is recommended to use an SSH tunnel. On your local machine, run:

```shell
ssh -N -L 18789:127.0.0.1:18789 root@server_IP
```

After establishing the connection, open the URL obtained earlier in your browser:

```shell
http://127.0.0.1:18789/?token=c6aaee5ae1fd9a7925892f4738f37deb01d2bd13d0c11199
```

## Updating OpenClaw

To update OpenClaw, run:

```shell
openclaw update
```

This command updates both OpenClaw and any installed plugins.

To check the current version, run:

```shell
openclaw --version
```

# Deploy Paperclip

Source: https://hostman.com/docs/cloud-servers/administration/paperclip/

[Paperclip](https://paperclip.ing/) is an open-source platform for managing a team of AI agents. It lets you bring agents and models together into a single system, assign them roles and tasks, track work progress and costs, and manage the whole process through a web interface. It's a good fit for scenarios where you need to coordinate several AI tools within one workflow.

## Installing Paperclip

To install Paperclip on a Hostman cloud server:

1.  Go to **[Cloud Servers](https://hostman.com/my/servers)** and click **Create Server**.
2.  Choose the region where the server will be deployed.
3.  In the **Image** step, open the **Marketplace** tab.
4.  Select the **AI** section and choose the **Paperclip** build.

![Create Server 2026 08 04 12 11](https://content.hostman.com/assets/b987765c-42c0-43f7-b11d-8e0c7e82d458.png?width=759&height=736)

5.  Select server configuration. You can leave the remaining settings at their defaults.
6.  Click **Create**.

Once the server is ready, you'll receive an email with a link to the automatic server setup script.

You can set up Paperclip in one of two ways:

-   Automatic setup
-   Manual setup

## Automatic Setup

Automatic setup is done using a ready-made script. It installs and configures Paperclip, along with OpenCode for working with AI models.

This method assumes you'll use [Hostman's AI agents](https://hostman.com/docs/ai-agents/) or [AI Gateway](https://hostman.com/docs/ai-agents/ai-gateway/) as your OpenAI-compatible API provider.

Before you start, make sure you already have [an AI agent created](https://hostman.com/docs/ai-agents/manage-agents/create/), or an [AI Gateway token issued](https://hostman.com/docs/ai-agents/ai-gateway/connection/#creating-an-api-key).

To set up Paperclip automatically:

1.  [Connect to your server over SSH](https://hostman.com/docs/cloud-servers/connect-to-server/).
    
2.  Run the setup script:
    

```shell
curl -fsSL "https://st.hostman.com/cloud-static/hostman-paperclip-autoinstall.sh" -o /tmp/hostman-paperclip-autoinstall.sh && chmod +x /tmp/hostman-paperclip-autoinstall.sh && sudo /tmp/hostman-paperclip-autoinstall.sh
```

3.  Enter the OpenAI API URL:
    

-   -   If you're using AI Gateway, enter:

```shell
https://ai-api.hostman.com/v1
```

-   -   If you're using an AI agent, you can find its [base URL](https://hostman.com/docs/ai-agents/api-usage/openai-compatible-api/#base-url) on the agent’s **Dashboard**.

4.  Enter the token for your chosen connection method. The characters won't be displayed as you type.
    
5.  Specify the model in the following format:
    

```shell
vendor/model_name
```

For example:

```shell
openai/gpt-5-mini
```

Once you've entered these parameters, the script will:

-   check and install dependencies
-   create a dedicated system user
-   configure OpenCode
-   create an administrator account
-   create a project in Paperclip

When the installation finishes, it displays a link to the Paperclip web interface along with the login details for the administrator account.

## Manual Setup

You can also set up Paperclip manually by creating a dedicated user, configuring server settings, setting up the service to start automatically, and creating an administrator account.

### Step 1. Create a User

1.  [Connect to your server over SSH](https://hostman.com/docs/cloud-servers/connect-to-server/) and create a dedicated user to run Paperclip under:
    

```shell
sudo adduser paperclip
```

2.  Add the user to the `sudo` group:
    

```shell
sudo usermod -aG sudo paperclip
```

3.  Switch to the newly created user:
    

```shell
su paperclip
```

### Step 2. Run the Initial Paperclip Setup

1.  Start the Paperclip setup:
    

```shell
paperclipai onboard
```

2.  Select **Quickstart**.
    
3.  When asked "Start Paperclip now?", answer **No**.
    
4.  Open the server configuration settings:
    

```shell
paperclipai configure --section server
```

5.  Set the following values:
    

-   -   **Reachability**: Custom
    -   **Server port**: 3100 (default value)
    -   **Auth mode**: Authenticated
    -   **Exposure profile**: Public internet
    -   **Bind host**: `0.0.0.0`
    -   **Public base URL**: the domain you'll use to access the service, or `http://server_IP` if you don't need a domain

6.  Once configuration is complete, check that Paperclip starts correctly. Run:
    

```shell
paperclipai run
```

7.  Open `http://server_IP:3100/` in your browser. If you see a message prompting you to create an administrator account, the service is working correctly.
8.  Go back to the terminal and stop the process with **Ctrl+C**.

### Step 3. Set Up Autostart with systemd

To have Paperclip start automatically after a server reboot, create a `systemd` service.

1.  Create a configuration file:
    

```shell
sudo nano /etc/systemd/system/paperclip.service
```

2.  Add the following content to it:
    

```shell
[Unit]
Description=Paperclip
After=network.target

[Service]
User=paperclip
WorkingDirectory=/home/paperclip
ExecStart=/usr/bin/paperclipai run
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

3.  Save the file.
    
4.  Reload the `systemd` configuration to pick up the new service:
    

```shell
sudo systemctl daemon-reload
```

5.  Enable the service so it starts automatically after a server reboot:
    

```shell
sudo systemctl enable paperclip
```

6.  Start Paperclip:
    

```shell
sudo systemctl start paperclip
```

Open `http://server_IP:3100` in your browser again. You should see the same prompt to create an administrator account.

### Step 4. Create an Administrator

1.  Run this command to create the first administrator account:
    

```shell
paperclipai auth bootstrap-ceo --force --base-url http://server_IP:3100
```

This command generates a one-time invitation link for registering an administrator. Example link:

```shell
http://server_IP:3100/invite/pcp_bootstrap_523d3256ea12afbb5e1f9d7f805233e9aecce5db58c85b17
```

2.  Open the link you received and click **Sign in / Create account**.
    

![14bbcf4b 236a 403d 9adb 829881b83b43.png](https://content.hostman.com/assets/ee9b99cd-5639-47a5-a07f-7c0fef15e5dd.png?width=1856&height=1014)

_[Paperclip](https://paperclip.ing/) authentication window_

3.  On the next screen, click **Create one** to create a new user. The email address is only used as a login—no emails will actually be sent to it.
    

4.  Fill in the form fields and click **Create account**.   
    If you're redirected back to the invitation page after creating your account, manually open `http://server_IP:3100`.
    

5.  Complete the initial setup and specify the connection details for your chosen agent provider.
    

After setup is complete, the Paperclip dashboard opens.

# Billing

Source: https://hostman.com/docs/billing/

You can manage service payments, check your current balance, view subscription fees, and track account transactions in the [Billing](https://hostman.com/my/finances/payment) section.

## Payment Model

Hostman uses a pay-as-you-go payment model and hourly billing. 

All cloud services on your account, such as Cloud servers, Images, Databases, App Platform etc. are billed hourly and charged to the account balance daily.

> [!NOTE]
> All services created on the account are billed, even if they're stopped and not in use. To stop charges for a service, you need to delete it from your Hostman account.

## Topping Up the Balance

You can top up your Hostman account balance using your bank card.

1.  Go to the **Billing** → **Payment** section.
2.  Select your preferred currency and enter the payment amount.
3.  If you want to [save your credit card](https://hostman.com/docs/billing/link-card/) for automatic balance top-ups, leave the **Link your card** checkbox selected. With a saved card, the balance is topped up automatically a week before your account runs out of funds.
4.  Click **Make a payment with Stripe**.
5.  On the Stripe payment page, enter your card details and complete the payment.

![77d99730 6572 4a1f 8568 Aaa195248b2b](https://content.hostman.com/assets/4f59d6fb-39f2-4e41-9765-c36b96c69498.png?width=1573&height=767)

## Active Services and Billing History

You can check the charges in the **Billing** → **Billing history** section.

![B9062e5e 4bb6 4825 8155 1f257d1524ab](https://content.hostman.com/assets/78f7fcb7-2e38-4eed-8fd8-ab62f75a5eb2.png?width=1556&height=1301)

To check which services currently exist on the account and are being billed, go to the **Active services** tab.

![41d8d8b4 E4d1 4a90 Abc2 16b7d508324c](https://content.hostman.com/assets/4f2e5423-38b7-4a3a-b4e3-0cb1b051f940.png?width=1567&height=1226)

For clarity, all services in the account are grouped by projects. This makes it possible to evaluate the budget of each project separately.

## Data Deletion Due to Insufficient Balance

If billing fails due to insufficient funds, the services will be suspended. You have 7 days to replenish your balance, after which the services will resume automatically.

If your account balance is not replenished within 7 days, all data and services will be permanently deleted.

# Link a Card

Source: https://hostman.com/docs/billing/link-card/

When making a payment, you can save your credit card in the Hostman dashboard by clicking **Link your card for convenient balance top-up** checkbox when making a payment. 

It will allow you to easily pay for the services without filling in the card details every time. To make a payment with your saved card, go to the **Billing** → **Payment** section, select the period or enter a sum and make the payment. The amount will be charged to your saved credit card.

Saving the card will also **enable automatic payments** for topping up your balance.

The automatic payments are made according to the terms and conditions below.

## Automatic Payments Terms and Conditions

-   Your credit card will be charged 7 days before the money on your balance runs out. If your previous payment was for 1 year, we will charge the amount necessary for 1 year. In other cases, payment for 1 month will be charged.
-   You will receive email notifications about all successful charges or unsuccessful attempts to charge your credit card. 
-   If an automatic payment fails, we will attempt to charge your card again in 6 hours. Further attempts will be repeated every 6 hours until the balance is replenished (automatically or manually for a period of at least 7 days) or until the account is blocked.

## Delete the Card

You can delete your linked credit card at any moment in the **Billing** → **Settings** section. 

Deleting the card will also stop all automatic payments.

# Terraform

Source: https://hostman.com/docs/terraform/

You can manage your Hostman infrastructure using Terraform.

Terraform allows you to automate resource management in Hostman with the help of convenient configuration files in HCL (HashiCorp Configuration Language) format and detailed plans of upcoming changes.

You can find more information on Terraform and working with it in the [HashiCorp Terraform documentation](https://developer.hashicorp.com/terraform/docs).

Comprehensive guides with examples on using Hostman Terraform provider is available in our [GitHub](https://github.com/hostman-cloud/terraform-provider-hostman).

# Get Started with Terraform

Source: https://hostman.com/docs/terraform/getting-started/

Terraform is a handy tool for quick provisioning and managing cloud infrastructure using configuration files.

When the configuration files change, Terraform automatically re-reads them and proceeds to create, update, or delete the resources, as described by the administrator.

In this article, we will describe how to begin working with Terraform and create cloud infrastructure in Hostman using it.

> [!NOTE]
> You can find more details on using Hostman Terraform provider in our [GitHub profile](https://github.com/hostman-cloud/terraform-provider-hostman).

## Step 1. Installing Terraform

First, let’s learn how to install Terraform on Linux, Windows, and macOS.

### Installing Terraform on Linux (Ubuntu)

You can run these commands as `root` or as a user with `sudo` privileges.

First, update the package list:

```shell
apt update
```

Next, install `wget` and `unzip` we’ll use later, navigate to the directory where Terraform will be installed, and download the package. Run these commands consecutively:

```shell
apt install wget unzip
cd ~
wget https://releases.hashicorp.com/terraform/1.12.2/terraform_1.12.2_linux_amd64.zip
```

In the last command, we specify the latest version as of writing—1.12.2. You can check the latest releases [here](https://developer.hashicorp.com/terraform/install). 

Now, unzip the archive:

```shell
unzip terraform_1.12.2_linux_amd64.zip
```

And move the file to the directory:

```shell
mv terraform /usr/local/bin/
```

That’s it. Now you can verify that Terraform is successfully installed:

```shell
terraform -v
```

If everything works correctly, you will see a similar output:

```shell
Terraform v1.12.2
on linux_amd64
```

### Installing Terraform on Windows

There are two ways of installing Terraform on Windows: via the Chocolatey package manager or manually.

While the Chocolatey method is straightforward, it won’t allow you to install the latest software version. If you want the latest version of Terraform, use the manual installation.

#### Via Chocolatey

The easiest way to install Terraform on Windows is using Chocolatey.

If you don’t have it yet, open PowerShell as administrator and run:

```shell
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
```

Now you can use Chocolatey to install software on your machine.

Enter the following command into PowerShell window to install Terraform:

```shell
choco install terraform
```

Verify that Terraform is successfully installed:

```shell
terraform -v
```

#### Manual Installation

To install the latest version of Terraform, follow these steps: 

1.  Go to the [HashiCorp website](https://developer.hashicorp.com/terraform/install) and select the version suitable for your system.
2.  Download the installation file.
3.  Extract the contents to a folder convenient for you, for example, `C:\Terraform`.

At this point, Terraform is installed; however, you can only use it when specifying the full path in the command line:

```shell
C:\Windows\system32>C:\Terraform\terraform -v
```

```shell
Terraform v1.12.2  
on windows_amd64
```

If you try to access Terraform by simply using its name, you will get an error:

```shell
C:\Windows\system32>terraform -v
```

```shell
'terraform' is not recognized as an internal or external command,  
operable program or batch file.
```

To be able to call terraform from the command line, you need to add it to the `PATH` environment variable. 

1.  Go to **Control Panel** → **System and Security**.
2.  Click on **Change system environment variables** in the **System** section. This will open the **System Properties** window
3.  Go to **Advanced** → **Environment Variables**.
4.  Find **PATH** in **System variables** and click **Edit**.
5.  Click **New** and enter the path to the directory where you extracted Terraform.
6.  Click **OK**.

Check that everything works well by running in the command line:

```shell
terraform -v
```

Output:

```shell
Terraform v1.12.2
on windows_amd64
```

### Installing Terraform on macOS

As with Windows, there are two ways of installing Terraform on your macOS machine: via the Homebrew package manager or by downloading the binary.

#### Via Homebrew

First, you need to install the official Hashicorp repository. Open the terminal and run:

```shell
brew tap hashicorp/tap
```

Next, you can install Terraform by running:

```shell
brew install hashicorp/tap/terraform
```

Check that the installation was successful by requesting the Terraform version:

```shell
terraform -v
```

#### Manual Installation on macOS

1.  Go to the [HashiCorp website](https://developer.hashicorp.com/terraform/install) and download the zip archive suitable for your system.
2.  Unzip it.
3.  List the locations in your `PATH` using the command:

```shell
echo $PATH
```

4.  Now, you need to place the Terraform executable file to one of the locations in the list. You can do it with the command:
    

```shell
mv ~/current/terraform/location /one/of/PATH/locations/
```

For example, if the executable is located in your **Downloads** and your PATH includes `/usr/local/bin`, the command will look like this:

```shell
mv ~/Downloads/terraform /usr/local/bin/
```

## Step 2. Creating the .tf Configuration File

Terraform configuration files have the `.tf` extension. The file name is arbitrary; the program can read it anyway.

Let’s create a new directory (`hostman_project`) and place a configuration file there. We’ll call it `hm_project.tf`.

To create a `.tf` file, you can first make a simple text file and then change its extension to `.tf`.

One directory can have several configuration files belonging to the same project. For example, you can create a `vars.tf` file for describing variables, `nginx.tf` for configuring an Nginx server, etc. When you run terraform plan, all the `.tf` files will be combined into one.

However, in this article, we’ll be using one configuration file, `hm_project.tf`.

## Step 3. Configuring the Provider

Now let’s configure the Terraform provider in our configuration file.

At the beginning of the `hm_project.tf` file add the following lines:

```shell
terraform {
  required_providers {
    hm = {
      source = "hostman-cloud/hostman"
    }
  }
  required_version = ">= 0.13"
}
```

In the `source` field, enter the provider URL. In this case, Hostman’s. 

Now navigate to the directory with the configuration file and run this command to install the provider:

```shell
terraform init
```

## Step 4. Obtaining a Token

To work with the provider, you will need an API token that you can obtain in the [API](https://my.hostman.com/api-keys) section of your Hostman dashboard.

1.  Click **Create**.
2.  Enter a token name; it will be displayed in the dashboard.
3.  Select the validity period for the token.
4.  Click **Issue**.
5.  Copy the issued token.

For example, we have obtained the token `fb246030216d5g30b1g6228e3071037g`. 

We need to add it to the `hm_project.tf` file like this:

```shell
provider "hm" {
  token = "fb246030216d5g30b1g6228e3071037g"
}
```

Make sure to replace `fb246030216d5g30b1g6228e3071037g` with your own token.

## Step 5. Preparing the Configuration

Using Terraform, you can manage various resources in your Hostman cloud, such as cloud servers, cloud databases, VPC, public IP addresses, etc.

As an example, let’s create a cloud server with the following specs:

-   NVMe: 80 GB
-   CPU: 2
-   RAM: 4 GB
-   OS: Ubuntu 22.04 

We’ll name the server `my-hostman-server`; you can set up your own name.

To create the server, add the following configuration into the `hm_project.tf` file:

```shell
data "hm_configurator" "configurator" {
  location = "us-2"
}

data "hm_os" "os" {
  name = "ubuntu"
 version = "22.04"
}

resource "hm_server" "my-hostman-server" {
  name = "My Hostman Server"
  os_id = data.hm_os.os.id

  configuration {
    configurator_id = data.hm_configurator.configurator.id
    disk = 1024 * 80
    cpu = 2
    ram = 1024 * 4
  }
}
```

If the program failed to create the server, check if you have entered the token correctly. 

Pay attention to the errors that Terraform displays; in most cases, they make it clear what went wrong.

Additionally, you can set up SSH key authentication. You can generate the keys using [this guide](https://hostman.com/docs/cloud-servers/ssh-keys/) in our documentation. Next, copy your public key to the server by adding the following configuration to the `hm_project.tf` file:

```shell
resource "hm_ssh_key" "your-key" {
  name = "Your key"
  body = file("~/.ssh/your-key.pub")
}
```

In the `resource` block, add the line `ssh_keys_ids`:

```shell
resource "hm_server" "my-hostman-server" {
 name = "My Hostman Server"
  os_id = data.hm_os.os.id

 ssh_keys_ids = [hm_ssh_key.your-key.id]
}
```

Our final configuration file should look like this:

```shell
terraform {
  required_providers {
    hm = {
      source = "hostman-cloud/hostman"
    }
  }
  required_version = ">= 0.13"
}

provider "hm" {
  token = "fb246030216d5g30b1g6228e3071037g"
}

data "hm_configurator" "configurator" {
  location = "us-2"
}

data "hm_os" "os" {
  name = "ubuntu"
  version = "20.04"
}

resource "hm_ssh_key" "your-key" {
  name = "Your key"
  body = file("~/.ssh/your-key.pub")
}

resource "hm_server" "my-hostman-server" {
  name = "My Hostman Server"
  os_id = data.hm_os.os.id

  ssh_keys_ids = [hm_ssh_key.your-key.id]

  configuration {
    configurator_id = data.hm_configurator.configurator.id
    disk = 1024 * 80
    cpu = 2
    ram = 1024 * 4
  }
}
```

## Step 6. Testing the Configuration

Use this command:

```shell
terraform validate
```

If all the settings are correct, you will see the message that the configuration is valid. If any errors occur, check your configuration again.

## Step 7. Applying the Configuration

First, enter the following command:

```shell
terraform plan
```

It doesn’t apply your configuration, but displays all the planned resources so you can check the settings. If there are any issues, Terraform will point you to the places in the configuration that are set incorrectly.

If and when everything is fine, run:

```shell
terraform apply
```

This command applies the configuration and allows Terraform to create the described resources. Confirm by typing `yes` and pressing **Enter**.

Now you can visit your Hostman dashboard and make sure the resources are created. 

Should you decide to remove them, you can use the command:

```shell
terraform destroy
```

In the next step, confirm the deletion by typing `yes`.

## Conclusion

In this guide, we described how to create Terraform configuration files and create and configure resources in the Hostman cloud.

To learn more about working with Terraform, refer to the [official documentation](https://developer.hashicorp.com/terraform/cli). And to find more about the Hostman Terraform provider, check [our GitHub page](https://github.com/hostman-cloud/terraform-provider-hostman).

# Kubernetes

Source: https://hostman.com/docs/kubernetes/

[Kubernetes](https://hostman.com/products/kubernetes/) is open-source software designed for automated management of containerized applications. It provides automatic deployment, scaling, load balancing, service monitoring, error handling, and much more.

Using Kubernetes offers numerous advantages, including the following key features:

#### Automatic Deployment

With Kubernetes, you can automate the process of creating new containers for deployment, removing existing containers, and reallocating resources to new containers. Applications deployed with Kubernetes will always run as intended.

#### Service Monitoring

Kubernetes automatically detects containers that have malfunctioned or stopped responding to requests and restarts them. If a container fails a specified health check, Kubernetes will terminate it and start a new container to replace it.

#### Network Load Balancing

Kubernetes balances network traffic to ensure stable deployment. If a container experiences high traffic, Kubernetes will restart it to balance the load.

#### Easy Migration

Kubernetes allows you to run an application in the same environment anywhere. You can easily migrate applications from local development machines to servers for deployment without worrying about compatibility issues.

#### Secure Storage of Sensitive Information

Passwords, OAuth tokens, and SSH keys are kept confidential. You can update application configurations without changing container images or exposing sensitive information in the stack configuration.

#### Automated Updates

As with other operations, the update process can be fully automated. Updates do not affect the current system operation, can be performed at a convenient time for development, and do not require the involvement of engineering teams.

#### Performance and Fault Tolerance

With flexible load management and extensive cluster scaling capabilities, Kubernetes ensures high system performance and fault tolerance.

# Create Clusters

Source: https://hostman.com/docs/kubernetes/create-clusters/

You can create a new [Kubernetes cluster](https://hostman.com/products/kubernetes/) in your Hostman dashboard.

1.  Go to the [Kubernetes](https://my.hostman.com/kubernetes/) section.
    
2.  Click **Create** or **Add**.
    
3.  Specify the cluster parameters.

**a.** **Kubernetes version**. You will be able to update it later by choosing an available later one.

**b. Master node configuration**:

-   -   **Dev**: supports up to 10 worker nodes. Uses a single master node with the parameters: 2 CPU, 2 GB RAM, 30 GB NVMe.
    -   **Base**: supports up to 100 worker nodes. Uses a single master node with the parameters: 4 CPU, 8 GB RAM, 60 GB NVMe.
    -   **Custom**: allows you to select 1 or 3 master nodes and configure worker nodes manually.

![C5fa3bf2 F41d 4fa8 B74c 91028d387169](https://content.hostman.com/assets/fb83bf15-ee28-433a-a913-622739d6bebe.png?width=749&height=570)

**c.** **Cluster [maintenance window](https://hostman.com/docs/kubernetes/manage-clusters/#cluster-maintenance-window)**, i.e. the time period during which system updates are allowed:

4.  Select worker nodes configuration. Create one or more node groups, select the number of nodes in each group, and choose a plan for them.
    

![5f69cd8f 54f2 470e A983 95245dbe6cf6](https://content.hostman.com/assets/54501e97-e907-426e-917e-183e19be5500.png?width=738&height=905)

Here, you can also configure: 

-   -   Autoscaling
    -   Autohealing
    -   Labels
    -   Taints

![7d1093b1 8d6e 4b44 A3ac 571759da5c4d](https://content.hostman.com/assets/ed731875-da41-4329-91be-6963c3a43935.png?width=711&height=299)

5.  Select an existing private network or create a new one. If necessary, configure a [CNI plugin](https://hostman.com/docs/kubernetes/cni/). It ensures full network connectivity between cluster nodes and affects the scalability and flexibility of network policy configuration.

![7f7ac74f Dbfc 4509 B799 00ed5d2a4aae](https://content.hostman.com/assets/1d8bafaf-46d2-4529-b03a-9b1826a61f0b.png?width=614&height=554)

6.  If necessary, set up an [OIDC provider](https://hostman.com/docs/kubernetes/oidc-provider-setup/).

![98d38c7a 58c5 430d Bcea 81b2895abace](https://content.hostman.com/assets/b67343a0-e121-4935-9cd5-6089fef223e9.png?width=619&height=664)

7.  Fill in the cluster information (name, comment, project) and click **Create**. The cluster creation will take a few minutes, after which you can start working.

# Connect to the Cluster

Source: https://hostman.com/docs/kubernetes/connect-to-clusters/

To work with [Kubernetes clusters](https://hostman.com/products/kubernetes/), you can use:

**Console utilities**:

-   [kubectl](https://hostman.com/docs/kubernetes/connect-to-clusters/kubectl/)

**GUI utilities**:

-   [Lens](https://hostman.com/docs/kubernetes/connect-to-clusters/lens/)
-   [Freelens](https://hostman.com/docs/kubernetes/connect-to-clusters/freelens/)
-   [Headlamp](https://hostman.com/docs/kubernetes/addons/headlamp/)
-   [Kubernetes Dashboard](https://hostman.com/docs/kubernetes/addons/#kubernetes-dashboard)

# kubectl

Source: https://hostman.com/docs/kubernetes/connect-to-clusters/kubectl/

`kubectl` is a command-line utility for working with [Kubernetes cluster](https://hostman.com/products/kubernetes/) entities. It allows you to manage cluster resources, deploy applications, view logs, and perform other administrative tasks.

> [!NOTE]
> Please note that the minor version of `kubectl` (the second digit in the version) may differ from the cluster version by +/- 1. Using newer or older versions may lead to compatibility issues. The instructions specify certain versions as examples, but you can replace them with the versions you need.

## Installing kubectl on Linux

There are two methods for installing `kubectl` on Linux.

### Installing with curl

1.  Download the `kubectl` binary:
    

```shell
curl -LO "https://storage.googleapis.com/kubernetes-release/release/v1.30.2/bin/linux/amd64/kubectl"
```

2.  Check the integrity of the file: 
    

```shell
echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/linux/amd64/kubectl.sha256) kubectl" | sha256sum --check
```

3.  Install `kubectl`: 
    

```shell
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
```

### Installing with apt

1.  Update the package list:
    

```shell
sudo apt update
```

2.  Install the required packages: 
    

```shell
sudo apt install -y apt-transport-https ca-certificates curl gnupg
```

3.  Add the key for the Kubernetes repository and set the correct permissions for the key: 
    

```shell
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.30/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg && sudo chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg
```

4.  Add the Kubernetes repository to the APT sources list and set the correct permissions on the sources list file: 
    

```shell
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list && sudo chmod 644 /etc/apt/sources.list.d/kubernetes.list
```

5.  Update the package list again: 
    

```shell
sudo apt update
```

6.  Install `kubectl`: 
    

```shell
sudo apt install -y kubectl
```

## Installing on macOS

For macOS, you can install `kubectl` manually or with Homebrew.

### Installing with Homebrew

Install `kubectl`: 

```shell
brew install kubectl@1.30
```

Or install the entire Kubernetes CLI toolchain:

```shell
brew install kubernetes-cli@1.30
```

> [!NOTE]
> The versions available for installation via Homebrew can be found on the [utility's official page](https://formulae.brew.sh/formula/kubernetes-cli).

### Manual Installation

**For Intel**

1.  Download `kubectl` for Intel: 
    

```shell
curl -LO "https://dl.k8s.io/release/v1.30.2/bin/darwin/amd64/kubectl"
```

2.  Check the integrity of the file: 
    

```shell
echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/darwin/amd64/kubectl.sha256) kubectl" | sha256sum --check
```

**For Apple Silicon**

1.  Download `kubectl` for Apple Silicon: 
    

```shell
curl -LO "https://dl.k8s.io/release/v1.30.2/bin/darwin/arm64/kubectl"
```

2.  Check the integrity of the file: 
    

```shell
echo "$(curl -sL https://dl.k8s.io/release/v1.30.2/bin/darwin/arm64/kubectl.sha256) kubectl" | sha256sum --check
```

3.  Make the file executable, set the permissions to `644`, move it to the `/usr/local/bin` directory and set the owner to `root`: 
    

```shell
chmod +x ./kubectl && chmod 644 ./kubectl && sudo mv ./kubectl /usr/local/bin/kubectl && sudo chown root: /usr/local/bin/kubectl
```

## Installing on Windows

You can install `kubectl` on Windows manually or with Chocolatey.

### Installation with Chocolatey

Install `kubectl` by running: 

```shell
choco install kubernetes-cli --version=1.30.2
```

### Manual Installation

1.  Open PowerShell and run:
    

```shell
mkdir kubectl
cd .\kubectl\
curl.exe -LO "https://dl.k8s.io/release/v1.30.2/bin/windows/amd64/kubectl.exe"
```

2.  Add the `kubectl` directory path to your `PATH` by running the following script in PowerShell:
    

```shell
$destination="$env:USERPROFILE\kubectl"
$currentPath = [System.Environment]::GetEnvironmentVariable("Path", [System.EnvironmentVariableTarget]::User)

if ($currentPath -notlike "*$destination*") {
[System.Environment]::SetEnvironmentVariable("Path", "$currentPath;$destination", [System.EnvironmentVariableTarget]::User)
}
```

Or add the path manually:

-   -   Right-click on **This PC**.
    -   Select **Properties**.
    -   Go to **About**.
    -   Click on **Advanced system settings**.
    -   Navigate to the **Advanced** tab.
    -   Click on **Environment Variables**.
    -   In the **System variables** section, find the **Path** variable and add the path to the `kubectl` directory.

3.  Restart PowerShell for the changes to take effect.
    

> [!NOTE]
> Docker Desktop for Windows adds its version of `kubectl` to the `PATH`. If you have Docker Desktop installed, you may need to place the `PATH` entry for `kubectl` before the one added by the Docker Desktop installer, or remove the version of `kubectl` installed by Docker Desktop.

`kubectl` is now installed on your machine. You can verify the installation by running the command:

```shell
kubectl version
```

## Configuring Access to the Kubernetes Cluster

To connect to the cluster, you will need the `kubeconfig` configuration file.

### Obtaining the kubeconfig Configuration File

The `config.yaml` file is used by `kubectl` to determine which cluster to connect to and what credentials to use. It contains information about clusters, users, and contexts, allowing for easy switching between different [Kubernetes](https://hostman.com/products/kubernetes/) configurations.

Since the `config.yaml` file contains important credentials, it should be stored in a location that is not accessible to unauthorized persons to prevent unauthorized access to the cluster. If an outsider gains access to this file, they can manage the cluster and its resources.

You can download the configuration file from the cluster's **Dashboard**.

![6c07bc59 Ed27 4ca2 935a 7f27c707b464](https://content.hostman.com/assets/f7811ed4-afbb-4b63-8156-98e339aa687b.png?width=1554&height=1006)

### Place kubeconfig in Your Home Directory

Once you have the `config.yaml` file, you need to place it in the correct directory so `kubectl` can use it.

#### macOS and Linux

1.  Create a `.kube` directory in your home directory if it doesn't exist yet:
    

```shell
mkdir -p ~/.kube
```

2.  Copy the `config.yaml` file to this directory and rename it to `config`:
    

```shell
cp ~/Downloads/config.yaml ~/.kube/config
```

After completing these steps, `kubectl` will automatically use the configuration from the `~/.kube/config` file.

#### Windows

1.  Open PowerShell.
    
2.  Create a `.kube` directory in your home directory if it doesn't already exist:
    

```shell
mkdir $env:USERPROFILE\.kube
```

3.  Copy the `config.yaml` file to this directory and rename it to `config`:
    

```shell
copy <path_to_config.yaml> $env:USERPROFILE\.kube\config
```

4.  Run PowerShell as administrator and execute:
    

```shell
[Environment]::SetEnvironmentVariable("KUBECONFIG", $HOME + "\.kube\config", [EnvironmentVariableTarget]::Machine)
```

After completing these steps, `kubectl` will automatically use the configuration from the `$env:USERPROFILE\.kube\config` file.

### Using the KUBECONFIG Environment Variable

If you need to use multiple configuration files or place `config.yaml` in a different location, you can use the `KUBECONFIG` environment variable.

#### macOS and Linux

1.  Open the terminal.
    
2.  Set the `KUBECONFIG` environment variable:
    

```shell
export KUBECONFIG=<path-to-your-kubeconfig>
```

To make these settings persist across system reboots, run the following code changing `~/.bashrc` to `~/.zshrc` (for MacOS) or `~/.profile` if necessary:

```shell
echo "export KUBECONFIG=<path-to-your-kubeconfig>" >> ~/.bashrc
```

#### Windows

1.  Open PowerShell.
    
2.  Set the `KUBECONFIG` environment variable:
    

```shell
$env:KUBECONFIG = "<path-to-your-kubeconfig>"
```

### Using multiple configuration files

You can specify multiple kubeconfig files by separating their paths with colons (on macOS and Linux) or semicolons (on Windows):

#### Windows

```shell
$env:KUBECONFIG="<path-to-your-first-kubeconfig>;<path-to-your-second-kubeconfig>"
```

#### macOS and Linux

```shell
export KUBECONFIG=<path-to-your-first-kubeconfig>:<path-to-your-second-kubeconfig>
```

## Setting Up a Connection to the Kubernetes Cluster

Once you have access set up, you need to make sure that `kubectl` can connect to the cluster. To do this, run the following command:

```shell
kubectl cluster-info
```

This command will output information about your cluster, including the addresses of the API and other components. If the command is successful, then `kubectl` is connected to the cluster.

### Checking a Context

Contexts allow you to switch between different clusters and credentials. Each context is a combination of clusters, users, and namespaces.

To see a list of available contexts and which one is currently active, use the command:

```shell
kubectl config get-contexts
```

This command will output a table of available contexts and indicate which one is currently active.

![Image3 (1)](https://content.hostman.com/assets/3bd54c38-8778-4139-904e-eea8f75fabae.png?width=810&height=117)

If you have multiple clusters configured and want to switch to a different context, use the following command:

```shell
kubectl config use-context <context-name>
```

Replace `<context-name>` with the context name that you got from the previous command. After running this command, `kubectl` will use the new context for all subsequent commands.

## Configuring Command Completion

Command completion helps you type commands faster and reduce errors by automatically suggesting possible options as you type. This is especially useful for long, complex `kubectl` commands.

### Installing bash-completion

1.  Install the `bash-completion` package.

**Ubuntu/Debian:**

```shell
sudo apt install bash-completion
```

**CentOS/RHEL:**

```shell
sudo yum install bash-completion
```

**macOS (Homebrew):**

```shell
brew install bash-completion
```

2.  Enable autocompletion for the current session.

**bash (Linux):**

```shell
source <(kubectl completion bash)
```

**zsh (macOS and Linux):**

```shell
source <(kubectl completion zsh)
```

3.  To always keep autocompletion enabled, run the command:

**bash (Linux):**

```shell
echo "source <(kubectl completion bash)" >> ~/.bashrc
```

**zsh (macOS and Linux):**

```shell
echo "source <(kubectl completion zsh)" >> ~/.zshrc
```

## Basic kubectl Commands

### Getting Cluster Information

To get general information about your cluster, including component addresses, use the command:

```shell
kubectl cluster-info
```

### Viewing Pods

To list all pods in the current namespace, use the command:

```shell
kubectl get pods
```

If you want to see pods in a specific namespace, add the `-n` option:

```shell
kubectl get pods -n <namespace>
```

### Viewing Services

To see all services in the current namespace, run the command:

```shell
kubectl get services
```

You can also specify a namespace:

```shell
kubectl get services -n <namespace>
```

### Viewing Configuration

To see the current configuration and active context:

```shell
kubectl config view
```

### Resources Description

To get detailed information about any resource, such as a pod or service:

```shell
kubectl describe <resource-type> <resource-name>
```

For example, to get information about a pod:

```shell
kubectl describe pod <pod-name>
```

### Deleting Resources

To delete a resource, such as a pod or service:

```shell
kubectl delete <resource-type> <resource-name>
```

For example, to delete a pod: 

```shell
kubectl delete pod <pod-name>
```

# Lens

Source: https://hostman.com/docs/kubernetes/connect-to-clusters/lens/

In this article, we will describe how to connect a [Kubernetes cluster](https://hostman.com/products/kubernetes/) to **Lens**, a desktop application for managing clusters.

## Lens Versions

Lens Desktop is available in three versions:

-   Lens Personal (free version)
-   Lens Pro (paid)
-   Lens Pro Enterprise (paid, for large companies)

## Creating a Lens ID

To use the free Lens version, go to the [Lens ID creation form](https://app.k8slens.dev/subscribe/personal/signup) and create a Lens ID. It will have a subscription for the free version. 

If you already have a Lens ID, click **Login with Lens ID**, enter your credentials, and log in. The free license will be added to your Lens ID.

## Installing Lens

1.  Download the installer for your operating system from the [official website](https://k8slens.dev/) and install it on your device.
2.  Launch the application.
3.  Select **New to Lens** if you don't have a Lens ID yet.

![Lens](https://content.hostman.com/assets/693465d3-99f3-4bdb-9577-6acbc3aa6cdc.png?width=685&height=744)

_The "Welcome to Lens" window in the [Lens](https://k8slens.dev/) installer_

4.  You'll be redirected to the Lens ID creation form. Enter your details and click **Create Lens ID**.

![7b74e5f7 52cd 4317 9afd 909dfe91b99a](https://content.hostman.com/assets/b5fe55df-a450-424d-9fb6-8b2e2d9d60ef.png?width=720&height=1084)

_Creating a Lens ID in the [Lens](https://k8slens.dev/) installer_

5.  Verify your email address by clicking on a link sent to you. A confirmation form will open.
6.  Enter your username and password and click **Login**.

![3cef0bd6 87d2 4cca 8ee4 7afa25d132ce](https://content.hostman.com/assets/a97ee232-e117-487b-9c61-1a4bb3a94346.png?width=736&height=794)

_Creating a Lens ID in the [Lens](https://k8slens.dev/) installer_

After successful login, the Lens Desktop will open.

## Connecting to the Cluster

You can save the configuration for connecting to the cluster in the default Lens folder or a custom one.

#### Using the Standard Folder

When using the standard folder (`~/.kube` or `~/.k8slens`, depending on the OS), you should see the name of your cluster in the **Catalog** → **Clusters** section. You can also access it from the welcome menu that appears after successful authorization in Lens by selecting **Browse Clusters in Catalog**.

#### Using the Custom Folder

1.  Create a folder named `k8s_config` in a location convenient for you (you can name the folder as you wish).
    
2.  Download the configuration file (`kubeconfig`) from the dashboard of the created cluster and place it in the folder you just created.
    

![6c07bc59 Ed27 4ca2 935a 7f27c707b464](https://content.hostman.com/assets/9cb0dd1c-6d15-429f-ba45-8a331f05604f.png?width=1554&height=1006)

3.  In the **Clusters** section, click the **+** button in the lower right corner and then add the configuration file(s) or the entire folder with files for initialization.
    

![Image2](https://content.hostman.com/assets/2bcbaf41-9fa6-4bfe-82c3-15b5e652e79d.png?width=1256&height=613)

_Lens Desktop. [Lens / Mirantis](https://k8slens.dev/)_

4.  Connect to the cluster by clicking on it.
    

![Image1](https://content.hostman.com/assets/0b88cb0d-2d33-4f31-9b88-07b8cfbf52d3.png?width=1338&height=492)

_Lens Desktop. [Lens / Mirantis](https://k8slens.dev/)_

You're all set! You are connected to the created [Kubernetes](https://hostman.com/products/kubernetes/) cluster.

![Image5](https://content.hostman.com/assets/310c1c7c-b06f-4de5-bd56-8881870feaa3.png?width=1362&height=682)

_Lens Desktop. [Lens / Mirantis](https://k8slens.dev/)_

You can learn about cluster management through the Lens IDE in the [official documentation](https://docs.k8slens.dev/).

# Freelens

Source: https://hostman.com/docs/kubernetes/connect-to-clusters/freelens/

Freelens is a fork of the popular Kubernetes cluster management tool, [Lens](https://hostman.com/docs/kubernetes/connect-to-clusters/lens/). Unlike the original Lens, Freelens is fully open-source, does not require registration or connection to cloud services, and contains no proprietary components.

## Installation

#### MacOS

To install Freelens on macOS using Homebrew:

```shell
brew install --cask freelens
```

#### Linux

On Linux, installation is available via Snap:

```shell
snap install freelens --classic
```

#### Windows

On Windows, use Winget:

```shell
winget install Freelensapp.Freelens
```

## Connecting to a Cluster

Freelens uses the standard `kubeconfig` for connecting to clusters. You can store configuration files in the default system directory `~/.kube`, or in any other convenient location.

Download the configuration file from the cluster’s **Dashboard**.

![E5e10f35 2347 4d3b 8720 7c6d92ad85f3](https://content.hostman.com/assets/cafc88e0-066d-42ce-b5f7-632a26b02962.png?width=1562&height=869)

### Using the Default Folder

If you place the downloaded `kubeconfig` in the `~/.kube` directory, Freelens will automatically detect the cluster. 

Go to **Catalog** → **Clusters**, and the cluster will appear in the list.

You can also access it using the **Browse Clusters in Catalog** button on the start screen.

### Custom Configuration Folder

If you want to use a separate directory:

1.  Create a folder, for example `~/k8s_config`, and move the downloaded `kubeconfig` file into it.
2.  In Freelens, open the **Clusters** section and click the **+** button in the lower right corner.
3.  Specify the path to the file or to a folder containing one or more `kubeconfig` files.
4.  After adding it, click the cluster name in the list to connect.

# Manage Clusters

Source: https://hostman.com/docs/kubernetes/manage-clusters/

Managing [Kubernetes clusters](https://hostman.com/products/kubernetes/) created in the Hostman dashboard.

-   [Dashboard](https://hostman.com/docs/kubernetes/manage-clusters/dashboard/)
-   [Related Services](https://hostman.com/docs/kubernetes/manage-clusters/related-services/)
-   [Master Node Configuration](https://hostman.com/docs/kubernetes/manage-clusters/master-node/)
-   [Managing Worker Nodes](https://hostman.com/docs/kubernetes/manage-clusters/worker-nodes/)
-   [Updating Kubernetes Version](https://hostman.com/docs/kubernetes/manage-clusters/update/)
-   [Cluster Maintenance Window](https://hostman.com/docs/kubernetes/manage-clusters/maintenance-window/)
-   [Autohealer](https://hostman.com/docs/kubernetes/manage-clusters/autohealer/)
-   [Deleting Clusters](https://hostman.com/docs/kubernetes/manage-clusters/delete/)

# Dashboard

Source: https://hostman.com/docs/kubernetes/manage-clusters/dashboard/

The **Dashboard** tab displays charts for CPU load, memory usage, pod capacity, pod statuses, and container restarts. The charts are available for both master and worker nodes.

To download the configuration file for connecting to the cluster, click the **d****ownload the configuration file** link on the right.

![De1f4ad4 3417 4be0 9472 3a4fc0511b22](https://content.hostman.com/assets/29fe1313-d2fe-458a-8f06-b1a2a517a41c.png?width=1542&height=1151)

#### CPU Core Load

-   **Capacity**: The total number of CPU cores on the node. Measured in cores or millicores.
-   **Allocatable**: The number of CPU cores available for scheduling applications on the node.
-   **Resource Limit**: The total CPU limit set for pods. This indicates the maximum CPU usage allowed for all pods on the node.
-   **Resource Request**: The total amount of CPU requested by all pods on the node.

![9221ebf9 Ce3f 48c8 98ed 638a3c5bc5ab](https://content.hostman.com/assets/fa6cd6a7-3c7b-436d-97da-cb7642cf72b6.png?width=721&height=384)

#### Memory

-   **Capacity**: The total amount of memory on the node.
-   **Allocatable**: The amount of memory available for scheduling applications.
-   **Resource Limit**: The total memory usage limit set for all pods on the node.
-   **Resource Request**: The total amount of memory requested by all pods.

![Ca744363 F224 48dc A22d 1ec7a5d4c1fe](https://content.hostman.com/assets/5fc98613-4453-488a-af45-7a6d288664cb.png?width=709&height=384)

#### Pods Capacity

-   **Allocatable**: The number of additional pods that can still be scheduled on the node.
-   **Requested**: The number of pods currently scheduled on the node.

![F6a0ea6a 625d 4ac0 9f27 A62ba8743b85](https://content.hostman.com/assets/bc8146d9-c43e-4920-8da7-9e21561f3eb8.png?width=711&height=362)

#### Pods Status

-   **Running**: The pod has been successfully deployed and is running. All containers within the pod are up and running.
-   **Failed**: An error occurred during the execution of one or more containers in the pod. For example, a container exited with a non-zero status code or failed to access required resources.
-   **Pending**: The pod has not started yet because Kubernetes is still scheduling it to a node and has not yet allocated the necessary resources (e.g., node space, networking, or image pulling). To find out the reason, run the command:

```shell
kubectl describe node <node_name>
```

-   **Unknown**: Kubernetes cannot determine the current status of the pod, possibly due to lost connection with the node where the pod was running. This may indicate connectivity issues or system failures.
-   **Succeeded**: All containers in the pod have successfully completed their work. This status typically applies to pods that are designed for one-time execution (e.g., a Job).

![94e6fc2a 33b5 45fb 986e 1a5d2e56f9fc](https://content.hostman.com/assets/6c4f74b0-1ee8-41a6-934e-539198004500.png?width=714&height=390)

# Related Services

Source: https://hostman.com/docs/kubernetes/manage-clusters/related-services/

In the **Related Services** section, you can view the resources connected to the Kubernetes cluster. All [load balancers](https://hostman.com/docs/kubernetes/load-balancing/) created from within the cluster will be displayed here.

Note that this applies only to load balancers created after **September 30, 2025**.

![Charming Grosbeak 04 15 2026 11 05 Am](https://content.hostman.com/assets/9a7d6924-bab3-477b-a7b7-0a6bf9a8b5f4.png?width=1570&height=777)

# Master Node Configuration

Source: https://hostman.com/docs/kubernetes/manage-clusters/master-node/

You can upgrade the configuration of master nodes after creating a cluster. Downgrading is not possible.

1.  Go to the **Kubernetes** section and click on the cluster.
2.  In the **Management** tab, click the **Select Configuration** button.

![66ad0904 5b73 4ba3 80e2 C7413525371f](https://content.hostman.com/assets/74902fb5-c60c-40d0-9e34-9bdee0a8cf2f.png?width=1561&height=970)

3.  Select the new master node configuration and click **Edit and reboot master node**.

![35afc3f8 44d6 472a 8ee4 45d240ca2ce3](https://content.hostman.com/assets/97cf94d2-60b4-48f1-9d02-4e2bd27d7259.png?width=1535&height=844)

# Worker Nodes

Source: https://hostman.com/docs/kubernetes/manage-clusters/worker-nodes/

In the **Resources** tab, you can view information about worker node groups.

Each node group contains only nodes with the same configuration. The configuration of each node is shown in its node group row.

When you expand a worker node group, you can view the local and external IP addresses of each node, as well as its creation date.

![View Node Groups](https://content.hostman.com/assets/cef10f80-47ca-4826-ae77-b64efc3171db.png?width=1583&height=783)

## Node Groups

You can add nodes to a group, configure group settings, and remove nodes.

### Add a Node Group

1.  Go to the **Kubernetes** section and select a cluster.
2.  Open the **Resources** tab.
3.  Click **Add groups**.
4.  Configure the group parameters:
    -   Set a name or use the default one
    -   Select the number and configuration of nodes
    -   (Optional) Enable [autoscaling](https://hostman.com/docs/kubernetes/autoscaling/)
    -   (Optional) Enable [autohealing](https://hostman.com/docs/kubernetes/manage-clusters/autohealer/)
    -   (Optional) Add labels and [taints](https://hostman.com/docs/kubernetes/manage-clusters/worker-nodes/#taint-effects) using the following formats:
        -   label: `key:value`
        -   taint: `key:value:effect`
5.  If you need multiple groups, click **+Add group** and configure them separately.
6.  Click **Add** to confirm.

### Add Nodes to a Group

1.  Go to the **Kubernetes** section and select a cluster.
2.  Open the **Resources** tab.
3.  Click on the three dots next to the node group and select **Add nodes**.

![9690a55a 0354 417e Baa1 9a4b8d4cf5db](https://content.hostman.com/assets/953c3d92-0c3d-4b6e-9b9d-c9d159a41870.png?width=1527&height=846)

4.  Select the number of nodes.
5.  (Optional) Add labels and [taints](https://hostman.com/docs/kubernetes/manage-clusters/worker-nodes/#taint-effects) using the following formats:
    -   label: `key:value`
    -   taint: `key:value:effect`
6.  Click **Add**.

![F88ce5b9 Abb7 4f53 8a21 E8384915bd7d](https://content.hostman.com/assets/d94bb9c5-9dec-4d4c-8280-838e11001864.png?width=1531&height=969)

### Configure a Node Group

1.  Go to the **Kubernetes** section and select a cluster.
2.  Open the **Resources** tab.
3.  Click on the three dots next to the node group and select **Edit group**.

![Edit Node Group](https://content.hostman.com/assets/44b93987-d00e-4242-b525-049f3bd67b30.png?width=1585&height=784)

4.  Update the settings:
    -   Change the group name
    -   Enable or disable [autoscaling](https://hostman.com/docs/kubernetes/autoscaling/)
    -   Enable or disable [autohealing](https://hostman.com/docs/kubernetes/manage-clusters/autohealer/)
    -   Add or remove labels and [taints](https://hostman.com/docs/kubernetes/manage-clusters/worker-nodes/#taint-effects) using the following formats:
        -   label: `key:value`
        -   taint: `key:value:effect`
5.  Click **Save**.

### Remove a Node Group

1.  Go to the **Kubernetes** section and select a cluster.
2.  Open the **Resources** tab.
3.  Click on the three dots next to the node group and select **Delete group**.
4.  Confirm the action.

![delete group](https://content.hostman.com/assets/aaf99035-9542-4e98-87a8-ee7090b98efa.png?width=1585&height=784)

## Nodes

You can manage individual nodes within a node group.

### Restart a Node

1.  Go to the **Kubernetes** section and select a cluster.
2.  In the **Resources** tab, expand the node group.
3.  Click on the three dots next to the node and select **Reboot node**.
4.  Confirm the action.

![Reboot Node](https://content.hostman.com/assets/31585dd5-6329-4a03-8d18-e6557b14194c.png?width=1583&height=829)

### Configure a Node

You can add or remove labels and taints:

1.  Go to the **Kubernetes** section and select a cluster.
2.  In the **Resources** tab, expand the node group.
3.  Click on the three dots and select **Edit node**.

![Edit Node](https://content.hostman.com/assets/63a57b71-e047-4e09-83a7-dc51e2617cb9.png?width=1588&height=828)

4.  Add or remove labels and [taints](https://hostman.com/docs/kubernetes/manage-clusters/worker-nodes/#taint-effects) using the following formats:
    -   label: `key:value`
    -   taint: `key:value:effect`
5.  Click **Save**.

### Remove a Node

1.  Go to the **Kubernetes** section and select a cluster.
2.  In the **Resources** tab, expand the node group.
3.  Click on the three dots next to the node and select **Delete node**.
4.  Confirm deletion.

![Delete node](https://content.hostman.com/assets/e2438730-395e-4147-b8d6-506bc7e70670.png?width=1588&height=828)

## Taint Effects

When adding a taint to a node or node group, you must select a taint effect.

The effect defines how the scheduler places pods on nodes:

-   `NoSchedule`: new pods are not scheduled on the node unless they have a matching `toleration`.
-   `PreferNoSchedule`: the scheduler avoids placing pods on the node when possible.
-   `NoExecute`: pods without a matching `toleration` are not scheduled on the node and are evicted if already running.

# Update Kubernetes Version

Source: https://hostman.com/docs/kubernetes/manage-clusters/update/

You can update the Kubernetes version in cluster settings. You can only select a newer version; rolling back to one of the older version isn't possible.

> [!NOTE]
> Changing the version might cause performance issues in the cluster. We recommend doing this during a time when the project has the least activity.

You can either start the update immediately or schedule it for a specific time that works best for you.

## Immediate Update

Use this option if you want the update to start right away.

1.  Go to the **Kubernetes** section and click on the cluster.
    
2.  In the **Management** tab, click **Update version**.
    

![061d1c27 Fbf2 4614 9e64 B4c7506c8446](https://content.hostman.com/assets/f790e531-36d7-462c-91dd-30ee25d51077.png?width=1541&height=968)

3.  Select the desired Kubernetes version.
    
4.  Leave the **Immediately** option selected.
    
5.  Click **Change**.
    

![Bb315b5b 2d67 4cf2 87b4 51563f3ab646](https://content.hostman.com/assets/aeb4f728-ba1c-42bc-aa75-8e0ef2f46ac2.png?width=1537&height=724)

The update will start as soon as you confirm the action.

## Scheduled Update

1.  Go to the **Kuberntes** section and click on the cluster.
2.  In the **Management** tab, click **Update version**.
    

![061d1c27 Fbf2 4614 9e64 B4c7506c8446](https://content.hostman.com/assets/f790e531-36d7-462c-91dd-30ee25d51077.png?width=1541&height=968)

3.  Select the desired Kubernetes version.
4.  Choose the **At a given time** option.
5.  Specify the preferred date and time.
6.  Click **Schedule.**

![E92d614a 7dfa 4331 94ed 198c100c58ff](https://content.hostman.com/assets/54bcf545-8df7-4c24-9704-792bbda42521.png?width=1554&height=794)

The update will start automatically at the scheduled time.

## Canceling a Scheduled Update

If the scheduled update is no longer needed, you can cancel it before it starts.

1.  Go to the **Kubernetes** section and click on the cluster.
    
2.  In the **Management** tab, click **Update version**.
    
3.  Click the cancel (**×**) icon next to the scheduled update.
    

![Fd95baef 3df4 49af 8603 315ed7a3a47e](https://content.hostman.com/assets/7a04bf10-ae73-4f2d-9f16-61f9a933c8bb.png?width=1543&height=791)

The scheduled update will be removed and will not be executed.

# Cluster Maintenance Window

Source: https://hostman.com/docs/kubernetes/manage-clusters/maintenance-window/

A cluster maintenance window is a period during which system updates are allowed. There are three available options:

-   Never
-   Any time
-   Specific time

During the maintenance window, certificates may be updated, and security patches may be installed. Updates can affect both master and worker nodes. During this time, operations on the cluster will be blocked. Short service interruptions may occur, for example, during node restarts.

You can set the maintenance window when creating a cluster, and you can manage it later in the cluster settings.

To change the maintenance window:

1.  In the **Kubernetes** section, click on the cluster.
2.  On the **Management** tab, click **Change** next to **Cluster maintenance window**.

![7fe738e6 82e6 4038 B88a E6a0d3ba5086](https://content.hostman.com/assets/2ea17eb4-1301-4512-876d-6136e8a2d78b.png?width=1511&height=972)

3.  Select the preferred maintenance window and save the changes.

# Autohealer

Source: https://hostman.com/docs/kubernetes/manage-clusters/autohealer/

The system automatically checks the status of worker nodes every 10 minutes. If a node stops responding, the autohealer attempts to restart it. Each attempt can take up to 2 minutes. If the node does not recover, the attempt is repeated. The autohealer will continue trying for up to 14 minutes. If all attempts fail, the node will be recreated.

You can enable or disable autohealing when editing a node group: the **Resources** tab → **Edit group**.

To disable autohealing for a specific node in the group, add the following label:

```shell
kube-healer.kubernetes.io/healing-disabled: true
```

No more than 10 autohealing tasks can be processed at the same time.

# Prometheus Exporter

Source: https://hostman.com/docs/kubernetes/manage-clusters/prometheus-exporter/

Prometheus Exporter is a component that collects metrics from a Kubernetes cluster and exposes them in a Prometheus-compatible format. It allows you to monitor cluster health, node load, and resource status.

## Accessing the Exporter

Exporter access details are available in your Hostman dashboard → **Kubernetes** → click on the cluster → **Dashboard**.

Public exporters require basic authentication to access metrics.

Example request to a public exporter:

```shell
curl -u admin:'password' -s https://k8s-exporter.hostman.dev/exporter_id/service/metrics
```

## Endpoints and Metrics

Two types of metrics are available:

-   `node_exporter` provides node-level metrics such as CPU usage, memory consumption, disk operations, and network traffic.
-   `kube_state_exporter` provides Kubernetes object metrics, including the state of pods, deployments, replicas, nodes, and other resources retrieved from the Kubernetes API.

Public endpoints:

-   Node metrics:

```shell
https://k8s-exporter.hostman.dev/exporter_id/node-exporter/metrics
```

-   Kubernetes metrics:

```shell
https://k8s-exporter.hostman.dev/exporter_id/service/metrics
```

`exporter_id` is the unique exporter identifier available in the dashboard.

## Implementation Details

Exporters are available in two modes:

-   Public, accessible over HTTPS with basic authentication
-   Private, accessible within a private network

Ports:

-   9100 for `node_exporter`
-   9308 for `kube_state_exporter`

For clusters with three master nodes, metrics must be collected from each node separately.

# Feature Gates

Source: https://hostman.com/docs/kubernetes/manage-clusters/feature-gates/

Feature gates allow you to enable or disable experimental Kubernetes functionality.

Features are available in different stages of maturity: **Alpha** and **Beta**. These stages indicate the level of stability and readiness for production use.

#### Alpha features

-   Disabled by default
-   May be unstable and contain bugs
-   Can be removed without notice
-   APIs may change unpredictably in future releases
-   Intended for testing purposes only

#### Beta features

-   Can be enabled by default
-   Considered relatively stable and well-tested
-   Will not be removed, but may still change
-   Backward-incompatible API changes are possible
-   Updating Kubernetes may require modifying or recreating resources
-   Recommended only for clusters running non-critical workloads

Cluster reliability is guaranteed only when default settings are used. Some feature gates are enabled by default.

When upgrading Kubernetes, feature gate settings are automatically reset to their default values, as some features may change or become unavailable in the new version.

The list of available features depends on the Kubernetes version. For a complete list and their statuses, refer to the [official Kubernetes documentation](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/#feature-gates-for-alpha-or-beta-features).

## Enable or Disable Feature Gates

To enable or disable a feature:

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Open the **Management** tab.
3.  Click **Configure** next to **Early access to features**.

![Early Access to Features](https://content.hostman.com/assets/d27d6aa9-2e01-439e-8aff-a6b5f7b2c304.png?width=1558&height=956)

4.  Enable or disable the required features.
5.  Click **Save**.
6.  Confirm the action.

![Early Access to Features](https://content.hostman.com/assets/3893818e-984d-4a99-a5ca-7545184e5061.png?width=1562&height=1022)

## Restore Default Settings

You can restore the default settings at any time, for example, to remove the impact of experimental features on the cluster.

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Open the **Management** tab.
3.  Click **Configure** next to **Early access to features**.
4.  Click **Restore defaults settings**.

The settings will be reverted immediately, without additional confirmation.

![Early Access to Features](https://content.hostman.com/assets/541e1813-b083-4343-8afc-4a1d5990b1e2.png?width=1562&height=1022)

# Cluster Logs

Source: https://hostman.com/docs/kubernetes/manage-clusters/logs/

In the **Logs** tab, you can view system logs for cluster components. This can help with cluster diagnostics and monitoring events related to cluster services.

You can customize how logs are displayed:

-   **Log time range**. Select the time interval for which log entries are displayed.
-   **Service filter**. Choose which cluster component logs to display. By default, logs from all services are shown, but you can filter them to display only specific services, such as the Autoscaler, Healer, CCM, or Kube API Server.

The section supports a maximum of 100,000 log lines per query.

![Group 1321314414 05 22 2026 12 15 Pm](https://content.hostman.com/assets/c584fe8f-a814-4364-b7fc-be35499e1d1e.png?width=1565&height=1163)

# Delete Clusters

Source: https://hostman.com/docs/kubernetes/manage-clusters/delete/

You can delete a cluster in two ways:

-   From the specific cluster's page by clicking on the delete icon.
    

![9c2336b7 Ef2c 4c80 85cc 91da9b892044](https://content.hostman.com/assets/ca877a18-f7e2-4484-ac8a-c24ddbfa090b.png?width=1505&height=768)

-   From the cluster list, click the three dots next to the cluster you want to delete and select **Delete cluster**.
    

![32fe7f44 24ac 45f9 A3b3 A2bcc524420a](https://content.hostman.com/assets/da1c0754-eb2b-413a-92c6-999c0ab4baf0.png?width=1543&height=701)

In the next window, enter the name of the cluster to be deleted and confirm the deletion.

# Autoscaling

Source: https://hostman.com/docs/kubernetes/autoscaling/

-   [Cluster Autoscaling in Kubernetes](https://hostman.com/docs/kubernetes/autoscaling/cluster-autoscaling/)
-   [Autoscaling Down to Zero Nodes](https://hostman.com/docs/kubernetes/autoscaling/autoscaling-to-zero/)

# Cluster Autoscaling

Source: https://hostman.com/docs/kubernetes/autoscaling/cluster-autoscaling/

Cluster autoscaling in [Kubernetes](https://hostman.com/products/kubernetes/) allows for flexible resource management by automatically adding or removing nodes and pods based on the workload.

## Cluster Requirements

The maximum number of nodes in a group cannot exceed the maximum allowable number of worker nodes in the cluster. For example, if the cluster limit is set to 100 nodes and one of the groups is already using 30 nodes, the new group can have a maximum of 70 nodes.

## Enabling Autoscaling

### For a New Cluster

To enable autoscaling during cluster creation, select the **Autoscaling** option in the **Worker nodes configuration** section.

The minimum number of nodes at the cluster creation stage is 1.

![1299452f Bc4a 4726 A94f Ee33435b032f](https://content.hostman.com/assets/edc7be3b-ea83-46ab-a4d1-5da919afbaf7.png?width=752&height=1248)

### For an Existing Cluster

If the cluster has already been created, you can enable autoscaling as follows:

1.  Navigate to the **Resources** tab.
2.  Click on the three dots next to the node group and select **Edit group**.
3.  Enable the autoscaling option for the group.

The minimum number of nodes is 0.

![1b067625 E048 42f9 8e17 9837fe130a27](https://content.hostman.com/assets/4bb3842b-9291-4926-8552-6371a2b9a0e7.png?width=1529&height=1074)

## Autoscaling Parameters

The following parameters are used to manage the creation and deletion of nodes:

```shell
--scale-down-unneeded-time 5m0s
--max-scale-down-parallelism 1
--provisioning-request-max-backoff-time 2m0s
--max-inactivity 3m0s
--scale-down-delay-after-add 2m0s
--max-node-provision-time 10m0s
--scan-interval 2m0s
--scale-up-from-zero=true
--scale-down-unready-enabled=true
--scale-down-unready-time=30m0s
```

| **Parameter** | **Description** |
| --- | --- |
| `scale-down-unneeded-time` | Time a node must remain idle before being removed (in this case, 5 minutes). |
| `max-scale-down-parallelism` | Maximum number of nodes that can be removed simultaneously (in this case, 1). |
| `provisioning-request-max-backoff-time` | Maximum wait time for node creation (3 minutes). |
| `max-inactivity` | Maximum inactivity time before node reduction can begin (3 minutes). |
| `scale-down-delay-after-add` | Delay time after adding a node before reduction can begin (3 minutes). |
| `max-node-provision-time` | Maximum time allowed for creating a new node (3 minutes). |

These parameters determine how quickly nodes are added or removed based on the current workload. For instance, if the workload decreases and a node remains idle for more than 5 minutes, it will be removed. However, node removal happens gradually to avoid a sudden reduction in resources. When the workload increases, new nodes are added, but this process is also controlled to prevent long delays, with a maximum time limit of 3 minutes.

In this way, autoscaling aims to maintain a balance between resource availability and cost-efficiency.

### Configuring Autoscaling Parameters

Autoscaling parameters are available for clusters running version 1.34 and later.

When creating or editing a node group (the **Resources** tab → **Edit group**), click **Advanced parameters**.

![Group Information 04 14 2026 10 55 Am](https://content.hostman.com/assets/c27e0a5e-23d7-45a9-a9e0-5d5ccc5f0e96.png?width=1573&height=1219)

Here, you can configure the following parameters:

-   `ScaleDownUtilizationThreshold`: the CPU or memory utilization threshold below which a node is considered a candidate for removal. Value range: 0 to 1. Default: 0.5.
-   `ScaleDownUnneededDuration`: the amount of time a node must remain underutilized before it is eligible for removal. Minimum value: 5 minutes. Default: 5 minutes.
-   `ScaleDownUnreadyDuration`: the time after which a node in the `NotReady` state may be removed. If the auto-healer is enabled, this parameter is ignored to avoid conflicts. Default: 15 minutes.
-   `MaxNodeProvisionDuration`: the maximum time to wait for a new node to be provisioned. If the node is not created within this period, the operation is considered failed. Default: 10 minutes.
-   `ZeroOrMaxNodeScaling`: node group scaling mode. When enabled, the group scales directly to either the maximum size or zero. When disabled, scaling occurs gradually, one node at a time. Default: disabled.
-   `IgnoreDaemonSetsUtilization`: whether to account for resources consumed by `DaemonSets` when deciding to remove a node. If enabled, they are ignored; if disabled, they are included. Default: disabled.

> [!NOTE]
> The parameters are applied to the cluster within 2 minutes after saving changes.

To restore the default parameters, click **Reset to default values**.

## Configuring Resources for Pods

Autoscaling works only if requests and limits are specified in the deployment. Below is an example of a deployment file:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: example-deployment
spec:
  selector:
    matchLabels:
      app: example
  template:
    metadata:
      labels:
        app: example
    spec:
      containers:
      - name: example-container
        image: example-image
        resources:
          requests:
            cpu: "200m"
            memory: "256Mi"
          limits:
            cpu: "400m"
            memory: "512Mi"
```

-   CPU limits are measured in millicores (`m`), where 1000m equals one core.
-   Memory limits are measured in megabytes (`Mi`) or gigabytes (`Gi`).

## Using nodeSelector and nodeAffinity

If a pod manifest uses `nodeSelector` or `nodeAffinity`, Kubernetes schedules the pod only on nodes that match the specified conditions. This also affects autoscaling: the autoscaler can create a new node only in a node group where the pod can be scheduled.

If no suitable node group exists, the pod will remain in the `Pending` state, even if autoscaling is enabled in the cluster.

### Example: nodeSelector

`nodeSelector` is suitable for simple cases where pods must run only on nodes with a specific label. For example, if an application should run only in a particular node group, you can use the following manifest:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: worker-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: worker
  template:
    metadata:
      labels:
        app: worker
    spec:
      nodeSelector:
        workload-type: background
      containers:
      - name: worker
        image: busybox
        command: ["sh", "-c", "sleep infinity"]
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
          limits:
            cpu: "200m"
            memory: "256Mi"
```

In this example, the pod can be scheduled only on nodes with the label `workload-type=background`. If no suitable nodes exist in the cluster, the autoscaler will be able to add a new node only to a group that uses this label.

### Example: nodeAffinity

`nodeAffinity` is used when more flexible scheduling rules are required. Unlike `nodeSelector`, it allows you to define expressions with different operators and combine multiple conditions.

Below is an example equivalent to the previous `nodeSelector`, but implemented using `nodeAffinity`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
            - matchExpressions:
              - key: workload-type
                operator: In
                values:
                - api
      containers:
      - name: api
        image: nginx:latest
        resources:
          requests:
            cpu: "200m"
            memory: "256Mi"
          limits:
            cpu: "400m"
            memory: "512Mi"
```

In this case, the pod will be scheduled only on nodes with the label `workload-type=api`. This example uses the In operator, which allows specifying one or more acceptable values for a label.

`nodeAffinity` also supports other operators, for example:

-   `In`: the label value must be in the specified list
-   `NotIn`: the label value must not be in the specified list
-   `Exists`: the label must be present on the node
-   `DoesNotExist`: the label must not be present
-   `Gt`: the label value must be greater than the specified value (for numeric values)
-   `Lt`: the label value must be less than the specified value (for numeric values)

These operators allow defining more advanced scheduling rules compared to `nodeSelector`.

Use `nodeSelector` when simple matching by one or more fixed values is sufficient. For more complex placement requirements, use `nodeAffinity`.

## Configuring Horizontal Pod Autoscaler (HPA)

The Horizontal Pod Autoscaler (HPA) is used to dynamically adjust the number of pods based on resource consumption, such as CPU or memory. HPA scales pods to maintain a specified level of resource usage and adapt to changing workload conditions. Below is an example of an HPA manifest:

```yml
apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: example-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: example-deployment
  minReplicas: 1
  maxReplicas: 5
  targetCPUUtilizationPercentage: 50
```

**HPA parameters:**

-   `apiVersion`: Specifies the API version used to create the resource. In this case, it is `autoscaling/v1`.
    
-   `kind`: The type of resource being created, here it is `HorizontalPodAutoscaler`.
    
-   `metadata`: Contains metadata information, including the name of the HPA (`example-hpa`).
    
-   `scaleTargetRef`: Specifies the object to scale, with the following details:
    

-   `apiVersion`: The API version of the resource being scaled.
    
-   `kind`: The type of resource to scale, in this case, `Deployment`.
    
-   `name`: The name of the resource to scale (`example-deployment`).
    

-   `minReplicas`: The minimum number of pod replicas to maintain, here it is set to `1`.
    
-   `maxReplicas`: The maximum number of pod replicas to scale up to, in this case, `5`.
    
-   `targetCPUUtilizationPercentage`: The CPU usage percentage at which the number of replicas will be adjusted. In this example, it is set to 50, meaning the number of replicas will be adjusted to maintain an average CPU utilization of 50%.
    

## Practical Example of Autoscaling

### Creating an Nginx Deployment for Autoscaling

To set up autoscaling, let’s create an Nginx deployment with defined resource limits:

`deployment.yaml`:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "1Gi"
```

This deployment creates an Nginx pod with specified resource limits, essential for the proper functioning of HPA.

### Setting Up Horizontal Pod Autoscaling for Nginx

To demonstrate pod autoscaling with Nginx, use the HorizontalPodAutoscaler (HPA) object. HPA automatically adjusts the number of pod replicas based on resource utilization.

`hpa.yaml`:

```yml
apiVersion: autoscaling/v1
kind: HorizontalPodAutoscaler
metadata:
  name: nginx-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: nginx-deployment
  minReplicas: 1
  maxReplicas: 4
  targetCPUUtilizationPercentage: 20
```

In this example, HPA adjusts the number of replicas for `nginx-deployment` based on CPU utilization, maintaining it at 20%.

### Setting Up a Load Balancer

To distribute load evenly among pods, it is recommended to use a Service object of the `LoadBalancer` type.

`service.yaml`:

```yml
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
spec:
  selector:
    app: nginx
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80
  type: LoadBalancer
```

This service provides access to pods using load balancing across multiple ports.

### Applying the Configuration

To apply the YAML files, use the following commands:

```shell
kubectl apply -f nginx-deployment.yaml
kubectl apply -f nginx-hpa.yaml
kubectl apply -f nginx-service.yaml
```

These commands will deploy the configurations for the Nginx deployment, HPA, and load balancer, creating all the necessary components for autoscaling.

### Demonstrating Node and Pod Scaling Under Load

Before generating load, ensure all resources are created and in the Running state. To observe autoscaling in action, generate load on the service using the hey tool, which sends HTTP requests to test performance.

Generate Load:

```shell
hey -z 10m -c 20 http://<load_balancer_ip>
```

This command generates 10 minutes of load with 20 parallel connections to the Nginx service, increasing resource usage and triggering scaling of pod replicas and, if necessary, worker nodes.

After some time, you can observe the scaling:

-   Check node scaling in the cluster:
    

```shell
kubectl get nodes
```

-   Check pod scaling, which will increase up to 4 replicas as defined in `hpa.yaml`:
    

```shell
kubectl get pods
```

# Autoscaling Down to Zero Nodes

Source: https://hostman.com/docs/kubernetes/autoscaling/autoscaling-to-zero/

Automatic scaling of a node group down to zero helps save resources when they are not being used. This is convenient for one-off tasks (for example, Jobs) or staging environments that remain inactive at night.

> [!NOTE]
> Scaling down to zero nodes is a special case of autoscaling. Therefore, the same principles, limitations, and requirements described for regular [autoscaling](https://hostman.com/docs/kubernetes/autoscaling/cluster-autoscaling/) also apply here.

## Requirements

For scaling down to zero to work, the cluster must have at least two additional nodes that remain permanently active. These nodes may belong to different groups. They are used to run Kubernetes system components.

## Pod Configuration

For the autoscaler to launch nodes in the desired group, specify the ID of that group in your manifest using `nodeSelector` or `nodeAffinity`.

You can use either the worker node group ID or [a custom label](https://hostman.com/docs/kubernetes/autoscaling/cluster-autoscaling/#using-nodeselector-and-nodeaffinity) assigned to the group as a condition. Labels provide flexible pod placement and avoid tight coupling to specific IDs.

#### How to Find the Group ID

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Open the **Resources** tab.
3.  Click the three dots next to the group and select **Edit group**.
4.  The group ID will be shown in the URL, for example:

```shell
https://my.hostman.com/kubernetes/1048329/54289/edit
```

Here:

-   `1048329`: cluster ID
-   `54289`: node group ID

Example with `nodeSelector`:

```yaml
nodeSelector:
  k8s.hostman.com/cluster-node-group-id: "54289"
```

Example with `nodeAffinity`:

```yaml
affinity:
  nodeAffinity:
    requiredDuringSchedulingIgnoredDuringExecution:
      nodeSelectorTerms:
      - matchExpressions:
        - key: k8s.hostman.com/cluster-node-group-id
          operator: In
          values:
          - "54289"
```

## When Scaling Down to Zero Won’t Work

The autoscaler will not be able to remove the last node in a group in the following cases:

-   The pod has the annotation: `cluster-autoscaler.kubernetes.io/safe-to-evict: "false"`
-   Pods cannot be moved to other nodes due to scheduler restrictions.
-   A `PodDisruptionBudget` prevents pods from being deleted without exceeding the limit.
-   The pod is not managed by a controller (`Deployment`, `StatefulSet`, `Job`, `ReplicaSet`).

## Practical Example

In this example, we’ll create a node group with autoscaling down to zero enabled, run a Job in it, and see how the cluster automatically creates a node to run the task and deletes it once the task is complete.

When creating a worker node group, you can define [custom labels](https://hostman.com/docs/kubernetes/autoscaling/cluster-autoscaling/#using-nodeselector-and-nodeaffinity) and use them for pod placement. In this example, the group ID is used for simplicity.

### Prerequisites

An existing Kubernetes cluster with at least one node group.

### Creating a Node Group with Zero Autoscaling

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Open the **Resources** tab.
3.  Click **Add group**.
4.  Select the worker node configuration.
5.  Enable the **Autoscaling** toggle and set the minimum number of nodes to **0**.

After the group is created, one node will appear and will be automatically deleted if no user pods are running on it.

Now the cluster has two groups:

-   A group with active nodes that do not scale down to zero.
-   A group with autoscaling down to zero enabled. In this example, its ID is 54289.

### Checking Existing Nodes

Run the command:

```shell
kubectl get nodes
```

Example output:

```shell
NAME                  STATUS   ROLES    AGE   VERSION
worker-192.168.0.25   Ready    <none>   21h   v1.33.3+k0s
worker-192.168.0.8    Ready    <none>   22h   v1.33.3+k0s
```

### Creating a Job

Create a file named `job.yaml` with the following content:

```yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: hello-job
spec:
  ttlSecondsAfterFinished: 30
  template:
    metadata:
      name: hello-job
    spec:
      restartPolicy: Never
      nodeSelector:
        k8s.hostman.com/cluster-node-group-id: "54289"
      containers:
      - name: hello
        image: busybox
        command:
          - sh
          - -c
          - 'i=0; while [ $i -lt 10 ]; do echo "Hello from job"; sleep 30; i=$((i+1)); done'
        resources:
          requests:
            cpu: "50m"
            memory: "32Mi"
          limits:
            cpu: "100m"
            memory: "64Mi"
```

This Job runs a container using the busybox image that writes a message to the log 10 times at 30-second intervals.

Note: In the `nodeSelector` section, we specify the node group ID (54289).

Apply the manifest:

```shell
kubectl apply -f job.yaml
```

Check the list of pods:

```shell
kubectl get pod
```

Example output:

```yaml
NAME              READY   STATUS    RESTARTS   AGE
hello-job-s7ktd   0/1     Pending   0          4s
```

The pod is in `Pending` status because there are no nodes in the group yet. Go to the **Resources** section in the management panel; you’ll see that a new node is being created in the autoscaling group.

After the node is created, check the nodes again:

```shell
kubectl get nodes
```

Example output:

```shell
NAME                  STATUS   ROLES    AGE   VERSION
worker-192.168.0.25   Ready    <none>   21h   v1.33.3+k0s
worker-192.168.0.6    Ready    <none>   7m    v1.33.3+k0s
worker-192.168.0.8    Ready    <none>   22h   v1.33.3+k0s
```

`worker-192.168.0.6` is the new node created for the Job.

Check the pod again:

```shell
kubectl get pod
```

Example output:

```shell
NAME              READY   STATUS    RESTARTS   AGE
hello-job-s7ktd   1/1     Running   0          5m30s
```

Now the pod is running.

### Job Completion and Node Deletion

After the Job completes, the node where it was running will be tainted. View the taint with:

```shell
kubectl describe node worker-192.168.0.6
```

Look for the line:

```shell
Taints:  DeletionCandidateOfClusterAutoscaler=1755679271:PreferNoSchedule
```

This means the node is marked for deletion. Two minutes after the taint is applied, the node will be removed.

Check it with:

```shell
kubectl get nodes
```

# Networking

Source: https://hostman.com/docs/kubernetes/networking/

-   [Network Plugins](https://hostman.com/docs/kubernetes/networking/cni/)
-   [Configuring Public and Private Services with Two Traefik Instances](https://hostman.com/docs/kubernetes/networking/configuring-public-and-private-services/)

# Network Plugins

Source: https://hostman.com/docs/kubernetes/networking/cni/

In [Hostman Kubernetes](https://hostman.com/products/kubernetes/), you can use various CNI (Container Network Interface) plugins, such as Calico, Flannel, Kube-router, and Cilium. These plugins facilitate pod connectivity to the network, manage routing, and enforce network policies, ensuring reliable and secure application performance.

Each of these plugins offers its own approach to addressing networking challenges in Kubernetes. Calico is suitable for high-performance networks with advanced security policies, Flannel stands out for its simplicity and reliability for basic networking tasks, Kube-router focuses on high-performance routing, and Cilium provides deep integration with the Linux kernel and advanced security features.

Let's examine the characteristics of each plugin to help you choose the right solution.

## Calico

Calico is a high-performance networking solution for Kubernetes that uses IP-based routing to ensure communication between pods and external networks.

**How It Works**

Calico uses BGP (Border Gateway Protocol) to exchange routes between cluster nodes. This allows each node to know where the pods are located and route packets directly, bypassing additional processing, which significantly improves performance.

**Network Policies**

One of the key advantages of Calico is its support for advanced network policies. These policies allow for the configuration of access control between pods at the network packet level, which is crucial for application security. For example, you can specify which pods are allowed to exchange data with each other.

**Advantages**

-   High performance due to non-overlay routing.
    
-   Scalability for large clusters.
    
-   Support for advanced network policies for security.
    

## Flannel

Flannel is a simple and lightweight network plugin used for creating overlay networks in [Kubernetes](https://hostman.com/products/kubernetes/).

**How It Works**

Flannel creates virtual networks using VXLAN or UDP protocols, allowing pods to communicate with each other. Each pod is assigned an IP address from a range reserved for the virtual network, and traffic is routed through tunnels between nodes.

**Network Policies**

Flannel does not provide advanced network policies like Calico and does not support BGP-based routing. This makes it less complex but suitable for simple networking scenarios, especially in small and medium clusters.

**Advantages**

-   Easy setup and operation.
    
-   Suitable for small clusters and cases where complex network policies are not required.
    

## Kube-router

Kube-router is a lightweight plugin that focuses on Layer 3 routing with minimal latency.

**How It Works**

Kube-router uses BGP to route traffic between pods on different nodes. It also provides network policy and load balancing features. Kube-router replaces the standard Kubernetes network stack, reducing complexity and overhead in processing network traffic.

**Network Policies**

In addition to routing, Kube-router provides traffic control through network policies and load balancing for IPVS (IP Virtual Server).

**Advantages**

-   High performance and low latency.
    
-   Support for network policies and load balancing.
    
-   Easy integration with clusters requiring high-performance routing.
    

## Cilium

Cilium is a powerful plugin that uses eBPF (extended Berkeley Packet Filter) for monitoring and managing network traffic at the operating system kernel level.

**How It Works**

Cilium utilizes eBPF to perform network operations directly in the Linux kernel, allowing for filtering, analyzing, and controlling network traffic with high precision and minimal processing overhead. This capability provides deep visibility into network flows and supports complex network policies at the application level.

**Network Policies**

Cilium supports standard Kubernetes network policies as well as advanced security features, such as HTTP request filtering and API interaction control.

**Advantages**

-   Support for deep traffic analysis and application-level security policies.
    
-   High performance due to integration with eBPF.
    
-   Scalability and the ability to implement complex network policies.

# Configuring Public and Private Services with Two Traefik Instances

Source: https://hostman.com/docs/kubernetes/networking/configuring-public-and-private-services/

When running a Kubernetes cluster that hosts both internet-facing and internal services, the cleanest approach is to split incoming traffic at the ingress controller level. You can do this by deploying two separate Traefik instances: one that handles public ingress, and one that handles private ingress.

This guide walks through that setup. You will deploy two Helm releases of Traefik with different `IngressClasses`, then route traffic to public and internal services accordingly.

## How It Works

Two independent Traefik instances run in the cluster:

-   `traefik-public` processes only Ingress resources with `ingressClassName: public`
-   `traefik-private` processes only Ingress resources with `ingressClassName: private`

Each instance creates its own `LoadBalancer` service with different parameters:

-   The public Traefik receives an external IP and accepts traffic from the internet
-   The private Traefik creates an internal load balancer with no public IP, accessible only within the private network

This lets you use a single cluster for both external and internal applications without mixing their entry points.

## Prerequisites

Before you begin, make sure you have:

-   [helm](https://hostman.com/docs/kubernetes/helm/) installed
-   A running Kubernetes cluster
-   Access to the cluster's [private network](https://hostman.com/docs/vpc/) for testing the private ingress (for example, via a separate cloud server in the same network)

## Configure Traefik

Both Traefik instances are deployed from the same Helm chart, but with separate values files.

### Public Traefik configuration

Create a file named `traefik-public-values.yaml` with the following content:

```yaml
fullnameOverride: traefik-public
 
ingressClass:
  enabled: true
  isDefaultClass: false
  name: public
 
service:
  enabled: true
  type: LoadBalancer
 
providers:
  kubernetesCRD:
    enabled: true
    allowCrossNamespace: false
    ingressClass: public
  kubernetesIngress:
    enabled: true
    ingressClass: public
    publishedService:
      enabled: true
```

This configures the public Traefik instance to handle ingress resources of the `public` class and create a standard `LoadBalancer` with an external IP.

Key settings to note:

-   `ingressClass.name: public` sets the class name that public Ingress resources will reference
-   `providers.kubernetesCRD.ingressClass` and `providers.kubernetesIngress.ingressClass` restrict Traefik to resources of its own class
-   `publishedService.enabled: true` enables correct publishing of the ingress service address

### Private Traefik configuration

Create a file named `traefik-private-values.yaml` with the following content:

```yaml
fullnameOverride: traefik-private
 
ingressClass:
  enabled: true
  isDefaultClass: false
  name: private
 
service:
  enabled: true
  type: LoadBalancer
  annotations:
    k8s.hostman.com/attached-loadbalancer-no-external-ip: "true"
 
providers:
  kubernetesCRD:
    enabled: true
    allowCrossNamespace: false
    ingressClass: private
  kubernetesIngress:
    enabled: true
    ingressClass: private
    publishedService:
      enabled: true
```

This configures the private Traefik instance to handle ingress resources of the private class and create an internal load balancer with no public IP.

The key parameter here is `k8s.hostman.com/attached-loadbalancer-no-external-ip: "true"`, which tells the platform to provision an internal load balancer without a public IP address.

## Install Both Traefik Instances

Add the Traefik Helm repository:

```shell
helm repo add traefik https://helm.traefik.io/traefik
helm repo update
```

Deploy the public instance:

```shell
helm install traefik-public traefik/traefik \
  -n traefik-public --create-namespace \
  -f traefik-public-values.yaml
```

Deploy the private instance:

```shell
helm install traefik-public traefik/traefik \
  -n traefik-public --create-namespace \
  -f traefik-public-values.yaml
```

Once both are installed, check that the `LoadBalancer` services have been created:

```shell
kubectl get svc -n traefik-public
kubectl get svc -n traefik-private
```

> [!NOTE]
> Load balancer provisioning can take up to 10 minutes. The `EXTERNAL-IP` column may show `pending` while the resource is being created.

Expected behavior differs between the two:

-   `traefik-public` should receive an external IP address
-   `traefik-private` will not receive an external IP, since it uses an internal load balancer

You can also check the status of both load balancers from the Hostman dashboard. Wait until both have finished provisioning before proceeding.

At this stage, also confirm that both ingress classes are registered in the cluster:

```shell
kubectl get ingressclass
```

The output should list both `public` and `private`.

## Routing Traffic to Public and Private Services

Once both Traefik instances are running, routing is as simple as setting the appropriate `ingressClassName` in each Ingress manifest.

For a public service:

```yaml
spec:
  ingressClassName: public
```

For a private service:

```yaml
spec:
  ingressClassName: private
```

All traffic is then routed through the corresponding ingress controller automatically.

## Practical Example

The following manifests demonstrate the full setup. The example includes:

-   Two public services: `service1` and `service2`
-   One private service: `service3`
-   Two Ingress resources with different `IngressClasses`

#### ConfigMap with test HTML pages

Create `config-map.yaml`:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: service-config
  namespace: ingress-example
data:
  service1.html: |
    <html>
      <head><title>Service 1</title></head>
      <body><h1>Welcome to Service 1!</h1></body>
    </html>
  service2.html: |
    <html>
      <head><title>Service 2</title></head>
      <body><h1>Welcome to Service 2!</h1></body>
    </html>
  service3.html: |
    <html>
      <head><title>Service 3</title></head>
      <body><h1>Welcome to Service 3!</h1></body>
    </html>
```

#### Public service1

Create `service1-deployment.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service1
  namespace: ingress-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service1
  template:
    metadata:
      labels:
        app: service1
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80
          volumeMounts:
            - name: config-volume
              mountPath: /usr/share/nginx/html
      volumes:
        - name: config-volume
          configMap:
            name: service-config
            items:
              - key: service1.html
                path: service1.html
---
apiVersion: v1
kind: Service
metadata:
  name: service1
  namespace: ingress-example
spec:
  selector:
    app: service1
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
```

#### Public service2

Create `service2-deployment.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service2
  namespace: ingress-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service2
  template:
    metadata:
      labels:
        app: service2
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80
          volumeMounts:
            - name: config-volume
              mountPath: /usr/share/nginx/html
      volumes:
        - name: config-volume
          configMap:
            name: service-config
            items:
              - key: service2.html
                path: service2.html
---
apiVersion: v1
kind: Service
metadata:
  name: service2
  namespace: ingress-example
spec:
  selector:
    app: service2
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
```

#### Private service3

Create `service3-deployment.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service3
  namespace: ingress-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service3
  template:
    metadata:
      labels:
        app: service3
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80
          volumeMounts:
            - name: config-volume
              mountPath: /usr/share/nginx/html
      volumes:
        - name: config-volume
          configMap:
            name: service-config
            items:
              - key: service3.html
                path: index.html
---
apiVersion: v1
kind: Service
metadata:
  name: service3
  namespace: ingress-example
spec:
  selector:
    app: service3
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
```

#### Public ingress

Create `ingress-public.yaml`:

```shell
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-public-ingress
  namespace: ingress-example
spec:
  ingressClassName: public
  rules:
    - host: ingress1.example.com
      http:
        paths:
          - path: /service1
            pathType: Prefix
            backend:
              service:
                name: service1
                port:
                  number: 80
          - path: /service2
            pathType: Prefix
            backend:
              service:
                name: service2
                port:
                  number: 80
```

Note that `spec.ingressClassName` is set to `public`, which means this Ingress will be handled by the public ingress controller.

#### Private ingress

Create `ingress-private.yaml`:

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-private-ingress
  namespace: ingress-example
spec:
  ingressClassName: private
  rules:
    - host: ingress2.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: service3
                port:
                  number: 80
```

Here `spec.ingressClassName` is set to `private`, so this Ingress will be handled by the private ingress controller.

#### Apply the manifests

Create the `ingress-example` namespace:

```shell
kubectl create namespace ingress-example
```

Apply all manifests:

```shell
kubectl apply -f config-map.yaml
kubectl apply -f service1-deployment.yaml
kubectl apply -f service2-deployment.yaml
kubectl apply -f service3-deployment.yaml
kubectl apply -f ingress-public.yaml
kubectl apply -f ingress-private.yaml
```

Verify that deployments, services, and ingress resources were created:

```shell
kubectl get deploy,svc,ingress -n ingress-example
```

You should see three services, three deployments, and two ingress resources. If anything is missing, the corresponding manifest either was not applied or contains an error.

With this setup:

-   Requests to `ingress1.example.com/service1...` are routed to `service1`
-   Requests to `ingress1.example.com/service2...` are routed to `service2`
-   Requests to `ingress2.example.com/` are routed to `service3`, accessible only from within the private network via the internal Traefik load balancer

## Verify the Setup

Before sending test requests, check that each ingress has the correct class assigned:

```shell
kubectl describe ingress example-public-ingress -n ingress-example
kubectl describe ingress example-private-ingress -n ingress-example
```

Confirm that `example-public-ingress` shows `Ingress Class: public` and `example-private-ingress` shows `Ingress Class: private`. If the class does not match, Traefik will not process that resource.

> [!NOTE]
> The example uses `ingress1.example.com` and `ingress2.example.com` as placeholder hostnames. You can use them with `curl --resolve` without configuring real DNS. If you want to open the public ingress in a browser, replace `ingress1.example.com` with a real domain and configure a DNS record pointing to the public load balancer IP.

Once the public load balancer has an external IP, test the routes:

```shell
curl http://ingress1.example.com/service1.html \
  --resolve ingress1.example.com:80:PUBLIC_LB_EXTERNAL_IP
 
curl http://ingress1.example.com/service2.html \
  --resolve ingress1.example.com:80:PUBLIC_LB_EXTERNAL_IP
```

Where `PUBLIC_LB_EXTERNAL_IP` is the external IP assigned to the public load balancer.

If you receive a 404, double-check that you are using the hostname `ingress1.example.com` and the paths `/service1` or `/service2`.

To test the private service, run the following from a machine inside the same private network as the cluster:

```shell
curl http://ingress2.example.com/ \
  --resolve ingress2.example.com:80:PRIVATE_LB_IP
```

Where `PRIVATE_LB_IP` is the private IP of the internal load balancer.

You should receive an HTML page served by `service3`.

If the private route does not respond, confirm that the request is coming from within the private network. External internet traffic cannot reach this ingress, even if the cluster resources are configured correctly.

# Load Balancing

Source: https://hostman.com/docs/kubernetes/load-balancing/

-   [Create a Load Balancer](https://hostman.com/docs/kubernetes/load-balancing/create/)
-   [Load Balancer Configuration Parameters](https://hostman.com/docs/kubernetes/load-balancing/parameters/)
-   [Configure a Custom SSL Certificate on a Load Balancer](https://hostman.com/docs/kubernetes/load-balancing/custom-ssl/)
-   [Deploy and Test a Load Balancer with Nginx](https://staging.hostman.com/docs/kubernetes/load-balancing/nginx-practical-example/)
-   [Troubleshoot Load Balancer Issues](Troubleshooting)

# Create a Load Balancer

Source: https://hostman.com/docs/kubernetes/load-balancing/create/

To ensure the stable operation of applications and evenly distribute traffic among pods in [Kubernetes](https://hostman.com/products/kubernetes/), you can use a load balancer. It helps avoid overloading individual pods, maintaining high availability and stability of services.

To create a load balancer in Kubernetes, we define a `Service` resource with the type `LoadBalancer`. Below is an example of a basic manifest:

```yml
apiVersion: v1
kind: Service
metadata:
  name: example-balancer
  namespace: kubernetes-dashboard
spec:
  selector:
    app.kubernetes.io/name: nginx
  ports:
    - port: 80            # External port for accessing the application
      targetPort: 80      # Pod port to which traffic is redirected
  type: LoadBalancer
```

In this example, the load balancer redirects traffic from port 80 to port 80 inside the pods matching the selector `app.kubernetes.io/name: nginx`.

If you need to add multiple rules for balancing, ensure that you specify the `name` attribute for each port:

```yml
apiVersion: v1
kind: Service
metadata:
  name: example-balancer
  namespace: kubernetes-dashboard
spec:
  selector:
    app.kubernetes.io/name: nginx
  ports:
    - port: 80
      targetPort: 80
      name: http
    - port: 443
      targetPort: 443
      name: https
  type: LoadBalancer
```

The value of the `name` attribute can be arbitrary.

For each port, you can specify the traffic protocol using the `appProtocol` attribute. This explicitly defines how the load balancer will handle traffic. By default, the value is `proto-tcp`.

The following values are supported:

-   `k8s.hostman.com/proto-http`: standard HTTP traffic
-   `k8s.hostman.com/proto-https`: HTTPS traffic
-   `k8s.hostman.com/proto-tcp`: TCP traffic
-   `k8s.hostman.com/proto-tcp-ssl`: TCP traffic with TLS support
-   `k8s.hostman.com/proto-http2`: HTTP/2 traffic

After creation, the load balancer will be visible in the management panel under the **Load Balancers** section, with a `k8s` label.

> [!NOTE]
> A load balancer created through Kubernetes can only be modified via `kubectl`, not through the dashboard or API.

# Configuration Parameters

Source: https://hostman.com/docs/kubernetes/load-balancing/parameters/

This article lists all parameters available for configuring a load balancer in Kubernetes. Use them to fine-tune balancing behavior, health checks, timeouts, and more.

## Available Parameters

Below is a table summarizing the available parameters for configuring a load balancer. Each parameter is specified as an annotation in the `Service` manifest:

| **Parameter** | **Purpose** |
| --- | --- |
| `k8s.hostman.com/attached-loadbalancer-preset-id: "391"` | Specifies the load balancer configuration. The default is the minimum configuration for the zone. Get preset IDs via API. |
| `k8s.hostman.com/attached-loadbalancer-algo: "roundrobin"` | Balancing algorithm: `roundrobin` or `leastconn`. |
| `k8s.hostman.com/attached-loadbalancer-healthcheck-check-interval: "10"` | Interval between health checks (in seconds). |
| `k8s.hostman.com/attached-loadbalancer-healthcheck-timeout: "5"` | Timeout for health checks (in seconds). |
| `k8s.hostman.com/attached-loadbalancer-healthcheck-error-count: "3"` | Number of failed checks before marking an upstream as unavailable. |
| `k8s.hostman.com/attached-loadbalancer-healthcheck-recover-count: "2"` | Number of successful checks needed to recover an upstream. |
| `k8s.hostman.com/attached-loadbalancer-no-external-ip: "true"` | Disables a public external IP for the load balancer. |
| `k8s.hostman.com/ignore-hostman-loadbalancer: "true"` | Excludes the service from Hostman load balancing. Useful when operating with a different LoadBalancer, such as `kube-vip` or `MetalLB`. |
| `k8s.hostman.com/attached-loadbalancer-ddos-guard-external-ip: "true"` | Assigns an external IP with DDoS protection. |
| `k8s.hostman.com/attached-loadbalancer-proxy-enable: "true"` | Enables proxy mode for the load balancer. When using this annotation, the receiving application (for example, an ingress controller or proxy) must also be configured to accept the proxy protocol. Otherwise, requests may fail with errors (for example, HTTP 400). See configuration examples in the official documentation: [Ingress NGINX](https://kubernetes.github.io/ingress-nginx/user-guide/miscellaneous/), [Traefik](https://doc.traefik.io/traefik/master/reference/install-configuration/entrypoints/). |
| `k8s.hostman.com/attached-loadbalancer-connect-timeout: "5000"` | Timeout for establishing a TCP connection with the upstream (in milliseconds). |
| `k8s.hostman.com/attached-loadbalancer-client-timeout: "50000"` | Timeout for receiving new TCP segments from the client (in milliseconds). |
| `k8s.hostman.com/attached-loadbalancer-server-timeout: "50000"` | Timeout for waiting for a response from the backend (in milliseconds). |
| `k8s.hostman.com/attached-loadbalancer-http-request-timeout: "10000"` | Timeout for executing an HTTP request (in milliseconds). |
| `k8s.hostman.com/attached-loadbalancer-maxconn: "10000"` | Maximum number of connections the load balancer can handle on the frontend. |
| `k8s.hostman.com/attached-loadbalancer-ssl: "true"` | Enables automatic SSL certificate issuance. If set to false, the certificate will be deleted. |
| `k8s.hostman.com/attached-loadbalancer-ssl-fqdn: "example.com"` | The domain for which the SSL certificate should be issued. |
| `k8s.hostman.com/attached-loadbalancer-ssl-type: "lets_encrypt"` | Specifies the SSL certificate type for the load balancer. Supported values: `lets_encrypt` and `custom`. |
| `k8s.hostman.com/attached-loadbalancer-force-ssl: "true"` | Enables automatic HTTP to HTTPS redirection using HTTP status code `307`. Requires a valid SSL certificate configuration through both `attached-loadbalancer-ssl` and `attached-loadbalancer-ssl-fqdn`. |

## Fine-Tuning with Annotations

For more flexible load balancer configuration in Kubernetes, you can use additional parameters. These are specified as `annotations` in the `Service` manifest.

Here’s an example manifest with parameters set via `annotations`:

```shell
apiVersion: v1
kind: Service
metadata:
  name: example-balancer
  namespace: kubernetes-dashboard
  labels:
    app: nginx
  annotations:
    k8s.hostman.com/attached-loadbalancer-algo: "leastconn"    
    k8s.hostman.com/attached-loadbalancer-ddos-guard-external-ip: "true" 
spec:
  selector:
    app.kubernetes.io/name: nginx
  ports:
    - port: 80
      appProtocol: k8s.hostman.com/proto-http
      targetPort: 80
  type: LoadBalancer
```

In this example, two additional parameters are defined:

-   `k8s.hostman.com/attached-loadbalancer-algo` is the load balancing algorithm. Here: `leastconn` (selects the server with the fewest active connections).
    
-   `k8s.hostman.com/attached-loadbalancer-ddos-guard-external-ip` assigns an external IP address to the load balancer with DDoS protection.
    

> [!NOTE]
> You can also define additional parameters via `labels`, but this is a legacy approach—some parameters may not apply correctly when using `labels`. We recommend using `annotations` instead.

## Service Annotations

In addition to user-defined parameters, the system may automatically add service annotations.

For example:

```yaml
metadata:
 annotations:
   k8s.hostman.com/lb-last-config: "..."
```

The `k8s.hostman.com/lb-last-config` annotation stores the last applied load balancer configuration. The cluster management system uses it to compare the current and the new configuration in order to determine whether the load balancer needs to be updated.

There is no need to modify or add this annotation manually.

## Configuring HTTPS Redirection

To enable HTTPS redirection, add the following annotation to your Service:

```shell
metadata:
  annotations:
    k8s.hostman.com/attached-loadbalancer-force-ssl: "true"
```

Before enabling HTTP to HTTPS redirection, make sure that the domain specified in `k8s.hostman.com/attached-loadbalancer-ssl-fqdn` already resolves to the load balancer IP address. This is required for Let's Encrypt to issue a certificate.

The `k8s.hostman.com/attached-loadbalancer-force-ssl` annotation redirects all incoming HTTP requests to HTTPS using HTTP status code `307`.

If `force-ssl` is enabled without a configured certificate and domain, the annotation is ignored and the load balancer continues serving regular HTTP traffic. The following warning is logged:

```shell
force-ssl requested but no SSL certificate configured; ignoring force-ssl
```

If the domain does not yet resolve to the load balancer IP address, Let's Encrypt will be unable to issue a certificate. In this scenario, the load balancer may still start redirecting requests to HTTPS even though no valid certificate is available. As a result, clients will receive TLS errors while the Kubernetes service itself may appear healthy.

Once HTTPS redirection has been enabled, it cannot be disabled by setting:

```shell
k8s.hostman.com/attached-loadbalancer-force-ssl: "false"
```

To disable HTTPS redirection, delete and recreate the `LoadBalancer` Service.

# Configure a Custom SSL Certificate on a Load Balancer

Source: https://hostman.com/docs/kubernetes/load-balancing/custom-ssl/

The Hostman load balancer supports custom SSL certificates stored as Kubernetes secrets of type `kubernetes.io/tls`. To enable HTTPS with your own certificate, create a TLS secret containing your certificate and private key, then reference it in the load balancer's annotations.

> [!NOTE]
> Self-signed certificates are not supported. You must use a certificate issued by a trusted Certificate Authority (CA).

## Create a TLS Secret

1.  Download your certificate files from your CA.
    
2.  Create a TLS secret in the same namespace as your load balancer:
    

```shell
kubectl -n <namespace> create secret tls my-app-tls \
  --cert=crt.crt \
  --key=key.key
```

3.  Verify the secret type:
    

```shell
kubectl -n <namespace> get secret my-app-tls -o yaml
```

The output should include:

```shell
type: kubernetes.io/tls
```

## Configure the Service

Add the following annotations to your load balancer manifest:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: my-app
  annotations:
    k8s.hostman.com/attached-loadbalancer-ssl: "true"
    k8s.hostman.com/attached-loadbalancer-ssl-type: "custom"
    k8s.hostman.com/attached-loadbalancer-ssl-fqdn: "example.com"
    k8s.hostman.com/attached-loadbalancer-ssl-secret-name: "my-app-tls"
spec:
  type: LoadBalancer
  selector:
    app: my-app
  ports:
    - name: https
      port: 443
      targetPort: 80
      appProtocol: k8s.hostman.com/proto-https
```

Annotation reference:

-   -   `k8s.hostman.com/attached-loadbalancer-ssl`: Enables SSL certificate support.
        
    -   `k8s.hostman.com/attached-loadbalancer-ssl-type`: Sets the certificate type. Use `custom` for your own certificate.
        
    -   `k8s.hostman.com/attached-loadbalancer-ssl-fqdn`: The domain name the certificate was issued for.
        
    -   `k8s.hostman.com/attached-loadbalancer-ssl-secret-name`: The name of the TLS secret containing the certificate and private key.
        

4.  Apply the changes:
    

```shell
kubectl apply -f service.yaml
```

## Verify the Certificate

Run the following command to check which certificate the load balancer is serving:

```shell
echo | openssl s_client \
  -connect example.com:443 \
  -servername example.com \
  2>/dev/null | openssl x509 -noout -subject -issuer -dates
```

A successful result looks like this:

```shell
subject=CN=example.com
issuer=C=BE, O=GlobalSign nv-sa, CN=GlobalSign GCC R6 AlphaSSL CA 2025
```

You can also verify the HTTPS connection using `curl`:

```shell
curl -kv https://example.com
```

Look for the following in the output:

```shell
SSL certificate verify ok.
```

And confirm your certificate details appear:

```shell
subject: CN=example.com
```

If you see the following instead:

```shell
subject: CN=empty
```

That means the load balancer could not apply your certificate and has fallen back to the default one. Double-check your secret name and annotations.

## Rotate the Certificate

To replace an existing certificate, update the secret in place:

```shell
kubectl -n <namespace> create secret tls my-app-tls \
  --cert=new.crt \
  --key=new.key \
  --dry-run=client -o yaml | kubectl apply -f -
```

After updating the secret, trigger a load balancer reconfiguration by touching any service annotation:

```shell
kubectl -n <namespace> annotate svc my-app \
  k8s.hostman.com/rotate-ts="$(date +%s)" \
  --overwrite
```

The Cloud Controller Manager (CCM) will re-read the secret and push the updated certificate to the load balancer.

## Practical Example

This example walks you through configuring a custom SSL certificate on a test Nginx application.

Prerequisites: a domain name and a valid certificate issued by a trusted CA.

### Create a Namespace

Create a dedicated namespace for testing:

```shell
kubectl create namespace test-namespace
```

### Deploy the Test Application

1.  Create a file called `nginx-deployment.yaml`:
    

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: test-namespace
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx-custom-cert-test
  template:
    metadata:
      labels:
        app: nginx-custom-cert-test
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80
```

2.  Apply the manifest:
    

```shell
kubectl apply -f nginx-deployment.yaml
```

3.  Confirm the pod is running:
    

```shell
kubectl get pods -n test-namespace
```

### Create a Load Balancer

1.  Create a file called `nginx-loadbalancer.yaml`:
    

```yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-loadbalancer
  namespace: test-namespace
spec:
  type: LoadBalancer
  selector:
    app: nginx-custom-cert-test
  ports:
    - name: https
      port: 443
      targetPort: 80
      appProtocol: k8s.hostman.com/proto-https
```

2.  Apply the manifest:
    

```shell
kubectl apply -f nginx-loadbalancer.yaml
```

3.  Wait for an external IP address to be assigned:
    

```shell
kubectl get svc nginx-loadbalancer -n test-namespace -w
```

Example output:

```shell
NAME                 TYPE           CLUSTER-IP       EXTERNAL-IP     PORT(S)
nginx-loadbalancer   LoadBalancer   10.101.130.253   203.0.113.10    443:31826/TCP
```

### Configure DNS

1.  Create an A record for your domain pointing to the load balancer's external IP.
    
2.  Confirm the domain resolves correctly:
    

```shell
dig +short example.com
```

The output should return the load balancer's IP address.

### Create the TLS Secret

1.  Create the TLS secret in the same namespace as your service:
    

```shell
kubectl -n test-namespace create secret tls my-app-tls \
  --cert=crt.crt \
  --key=key.key
```

2.  Verify the secret was created correctly:
    

```shell
kubectl -n test-namespace get secret my-app-tls -o yaml
```

The output should include:

```shell
type: kubernetes.io/tls
```

3.  Optionally, inspect the certificate directly from the secret:
    

```shell
kubectl -n test-namespace get secret my-app-tls \
  -o jsonpath='{.data.tls\.crt}' \
  | base64 -d \
  | openssl x509 -noout -subject -issuer -dates
```

### Apply the Certificate to the Load Balancer

1.  Add the SSL annotations to your `nginx-loadbalancer.yaml` manifest:
    

```yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-loadbalancer
  namespace: test-namespace
  annotations:
    k8s.hostman.com/attached-loadbalancer-ssl: "true"
    k8s.hostman.com/attached-loadbalancer-ssl-type: "custom"
    k8s.hostman.com/attached-loadbalancer-ssl-fqdn: "example.com"
    k8s.hostman.com/attached-loadbalancer-ssl-secret-name: "my-app-tls"
spec:
  type: LoadBalancer
  selector:
    app: nginx-custom-cert-test
  ports:
    - name: https
      port: 443
      targetPort: 80
      appProtocol: k8s.hostman.com/proto-https
```

2.  Apply the updated manifest:
    

```shell
kubectl apply -f nginx-loadbalancer.yaml
```

3.  Verify the service annotations are set:
    

```shell
kubectl -n test-namespace get svc nginx-loadbalancer -o yaml
```

The annotations section should include:

```shell
k8s.hostman.com/attached-loadbalancer-ssl: "true"
k8s.hostman.com/attached-loadbalancer-ssl-type: custom
k8s.hostman.com/attached-loadbalancer-ssl-fqdn: example.com
k8s.hostman.com/attached-loadbalancer-ssl-secret-name: my-app-tls
```

Once the CCM has successfully read the certificate, a hash annotation will appear:

```shell
k8s.hostman.com/attached-loadbalancer-ssl-cert-hash: ...
```

This confirms the certificate has been picked up from the secret.

### Verify the Application

Open your domain in a browser. If the certificate was applied correctly, the browser will establish a secure HTTPS connection without any warnings.

You can also test with `curl`:

```shell
curl -I https://example.com
```

A successful response confirms that:

-   the certificate has been loaded onto the load balancer;
    
-   the HTTPS connection is established correctly;
    
-   the load balancer is forwarding requests to your application running in Kubernetes.
    

### Clean Up

When you're done testing, delete the namespace to remove all associated resources, including the Deployment, Service, and TLS secret:

```shell
kubectl delete namespace test-namespace
```

# Deploy and Test a Load Balancer with Nginx

Source: https://hostman.com/docs/kubernetes/load-balancing/nginx-practical-example/

To demonstrate the functionality of a load balancer, we will create two Nginx deployments, each displaying its own HTML page. The load balancer will distribute requests randomly between the pods, showing one of the pages depending on which pod is selected.

## Environment Setup

To simplify management and allow quick removal of all resources associated with the load balancer, we will create a separate namespace. This makes testing and resource cleanup easier while keeping the main cluster clean.

Run the following command to create the namespace:

```shell
kubectl create namespace test-namespace
```

After creation, use this namespace for all subsequent resources, including the load balancer, deployments, and `ConfigMap`. To do this, add the line `namespace: test-namespace` to every manifest related to the example.

## Create a ConfigMap for HTML Pages

We will start by creating a `ConfigMap` to store two HTML pages. Pod 1 will display a page with the heading "Pod 1," and Pod 2 will display a page with the heading "Pod 2." These pages will be connected to Nginx within the pods.

`nginx-pages-configmap.yaml`:

```yml
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-pages
  namespace: test-namespace
data:
  index-page1.html: |
    <html>
    <body>
      <h1>Pod 1</h1>
      <p>This is page served by Pod 1.</p>
    </body>
    </html>
  index-page2.html: |
    <html>
    <body>
      <h1>Pod 2</h1>
      <p>This is page served by Pod 2.</p>
    </body>
    </html>
```

Here we create a `ConfigMap` with two HTML files: `index-page1.html` and `index-page2.html`. These files will be mounted into Nginx pods, allowing each pod to display its specific page.

Apply the `ConfigMap`:

```shell
kubectl apply -f nginx-pages-configmap.yaml
```

## Create Nginx Deployments

Next, we create two deployments, each using different HTML pages from the `ConfigMap`. The deployments use the selector `app: nginx`, which the load balancer will use to identify pods participating in traffic distribution.

`nginx-deployment-pod1.yaml`:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-pod1
  namespace: test-namespace
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        volumeMounts:
          - name: nginx-pages
            mountPath: /usr/share/nginx/html/index.html
            subPath: index-page1.html
        ports:
          - containerPort: 80
      volumes:
      - name: nginx-pages
        configMap:
          name: nginx-pages
```

This deployment creates a single pod (replica 1) with the Nginx image, which mounts the `index-page1.html` file from the `ConfigMap` into the directory `/usr/share/nginx/html/index.html`. Port 80 is open for accessing the page.

Apply the deployment:

```shell
kubectl apply -f nginx-deployment-pod1.yaml
```

`nginx-deployment-pod2.yaml`:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-pod2
  namespace: test-namespace
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          volumeMounts:
            - name: nginx-pages
              mountPath: /usr/share/nginx/html/index.html
              subPath: index-page2.html
          ports:
            - containerPort: 80
      volumes:
        - name: nginx-pages
          configMap:
            name: nginx-pages
```

This deployment also creates an Nginx pod but mounts the `index-page2.html` file, which has different content.

Apply the second deployment:

```shell
kubectl apply -f nginx-deployment-pod2.yaml
```

## Configure the Load Balancer

Now, create a load balancer that will direct requests to pods with the label `app: nginx`.

`nginx-loadbalancer.yaml`:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-loadbalancer
  namespace: test-namespace
spec:
  selector:
    app: nginx
  ports:
    - port: 80
      targetPort: 80
      appProtocol: k8s.hostman.com/proto-http
  type: LoadBalancer
```

In this `Service`, we specify `type: LoadBalancer`, which creates a load balancer, and `selector: app: nginx`, which directs requests to the Nginx pods from our deployments. Requests to the load balancer are distributed among the pods using the `roundrobin` algorithm, which is the default.

Apply the load balancer:

```shell
kubectl apply -f nginx-loadbalancer.yaml
```

## Verify the Load Balancer

After creating the load balancer, you can find its public IP address in the dashboard or by running the command:

```shell
kubectl get services -n test-namespace
```

Accessing this IP address will display a page served by one of the pods. Each time you refresh the page, traffic may be redirected to different pods, allowing the load balancer to switch the displayed page randomly.

## Deleting Resources After Testing

Once you have verified the load balancer’s functionality, you can delete all the created pods and resources. Use the following commands:

```shell
kubectl delete service nginx-loadbalancer -n test-namespace
kubectl delete deployment nginx-pod1 -n test-namespace
kubectl delete deployment nginx-pod2 -n test-namespace
kubectl delete configmap nginx-pages -n test-namespace
```

These commands will remove the load balancer, pod deployments, and the `ConfigMap` created earlier.

Alternatively, delete the entire namespace:

```shell
kubectl delete namespace test-namespace
```

This method will automatically remove all resources associated with the test environment.

# Troubleshooting

Source: https://hostman.com/docs/kubernetes/load-balancing/troubleshooting/

This article covers common issues you may encounter with load balancers in Kubernetes and how to resolve them.

## Failed to Obtain IP

If a load balancer fails to obtain an external IP address during creation, the following annotation will appear in the service:

```shell
k8s.hostman.com/attached-loadbalancer-ensuring-error: true
```

This means something went wrong while binding the external IP. In this case, we recommend recreating the load balancer or contacting technical support.

How to check:

1.  List all services of type LoadBalancer in the cluster:

```shell
kubectl get svc --all-namespaces --field-selector spec.type=LoadBalancer
```

2.  View the annotations of the desired service:

```shell
kubectl describe svc <service-name> -n <namespace>
```

3.  If the output contains the following annotation, recreate the load balancer or contact support and provide your cluster ID.

```shell
k8s.hostman.com/attached-loadbalancer-ensuring-error: true
```

# Addons

Source: https://hostman.com/docs/kubernetes/addons/

[Hostman Kubernetes](https://hostman.com/products/kubernetes/) clusters support various add-ons that can be used to extend functionality. Add-ons help manage traffic, monitor services, work with storage, and ensure security.

Some add-ons, such as Nginx Ingress, Kubernetes Dashboard, and CSI S3, can be installed both during cluster creation and later. You can manage the installation and removal of add-ons in the **Addons** tab of the cluster management panel.

Add-ons that are not available in the dashboard can be installed manually using [Helm](https://hostman.com/docs/kubernetes/helm/).

## Capsule

Capsule is an add-on that implements the concept of multi-tenancy in Kubernetes, ensuring resource isolation and consumption control between different user groups.

**How It Works**

Capsule allows the creation of logical tenants based on namespaces with annotations and policies, giving users the ability to manage their resources without affecting others.

**Key Features**

-   Resource isolation between users.
-   Management of quotas and limits.
-   Security policy configuration for different users.

## cert-manager

[cert-manager](https://hostman.com/docs/kubernetes/addons/cert-manager/) is a Kubernetes add-on that automates the issuance, renewal, and management of TLS certificates.

**How It Works**

cert-manager automatically requests and renews certificates, managing their lifecycle using CRD objects (CertificateRequest, Issuer, ClusterIssuer). It supports integration with various certificate providers, such as Let's Encrypt, HashiCorp Vault, and internal certificate authorities.

**Key Features**

-   Automatic certificate issuance.
-   Certificate renewal upon expiration.
-   Support for multiple providers (ACME, Vault, self-signed).

## Cluster Proportional Autoscaler

[Cluster Proportional Autoscaler](https://hostman.com/docs/kubernetes/addons/cpa/) (CPA) is a controller that automatically scales a specified deployment based on the number of nodes or CPU cores in the cluster. 

CPA is particularly useful for services that need to scale proportionally to cluster resources, such as metrics-server or CoreDNS.

**How It Works**

Unlike the Horizontal Pod Autoscaler, CPA does not rely on load metrics. Instead, scaling is determined by formulas based on the number of nodes and/or CPU cores. Two modes are supported:

-   **Linear**: the number of replicas is calculated using a defined formula that considers node and CPU counts.
-   **Ladder**: the number of replicas is explicitly set in a lookup table (e.g., 2 nodes → 2 pods).

**Key Features**

-   Scaling of deployments without using load metrics.
-   Support for both linear and table-based (ladder) scaling modes.
-   Takes into account both schedulable and unschedulable nodes.
-   Flexible configuration through Helm.
-   Support for multiple CPA instances for different purposes.

## CSI S3

[CSI S3](https://hostman.com/docs/kubernetes/addons/csi-s3/) is a plugin for the Container Storage Interface (CSI) that allows the use of [S3-compatible storage](https://hostman.com/products/s3-storage/) with Kubernetes.

**How It Works**

CSI S3 enables the dynamic attachment of object storage compatible with S3 (such as Ceph, MinIO, AWS S3) as standard persistent volumes for use in Kubernetes. This is particularly useful for storing large amounts of data in containerized applications.

**Key Features**

-   Connecting [S3 storage](https://hostman.com/products/s3-storage/) as persistent volumes
-   Support for dynamic volume creation and deletion
-   Flexibility in using various S3-compatible storage systems

## Fluent Operator

[Fluent Operator](https://hostman.com/docs/kubernetes/addons/fluent-operator/) is a Kubernetes operator for managing Fluentd and Fluent Bit, automating log collection, routing, and processing within a cluster.

**How It Works**

Fluent Operator uses CRDs to manage Fluentd and Fluent Bit configurations, enabling container and system logs to be directed to various storage solutions such as Elasticsearch, Loki, Kafka, and others.

**Key Features**

-   Centralized log collection and management.
-   Flexible log routing to different storage systems.
-   Configuration of log filtering, aggregation, and processing.

## Grafana Loki

[Grafana Loki](https://hostman.com/docs/kubernetes/addons/grafana-loki/) is a log aggregation and visualization system developed by Grafana Labs. It is used together with Grafana to provide convenient Kubernetes log visualization.

**How It Works**

Unlike traditional logging stacks (e.g., ELK), Loki does not index the contents of logs. Instead, it stores log data alongside metadata (such as pod name, namespace, etc.), which makes the system more resource-efficient.

Logs are collected using the Promtail agent installed on each node and sent to Loki. Logs are viewed in Grafana using the LogQL query language.

**Key Features**

-   Collection of logs from Kubernetes pods.
-   Storage of logs with associated metadata.
-   Log visualization in Grafana.
-   Querying and filtering logs using LogQL.
-   Integration with alternative agents (Fluent Bit, Filebeat, Logstash).

## Istio

Istio is a Service Mesh that provides traffic management, security, and monitoring for services in Kubernetes.

**How It Works**

Istio injects sidecar proxies (Envoy) into each pod, enabling request routing, authentication, and monitoring within the service mesh.

**Key Features**

-   Traffic routing.
-   Flexible security policy management.
-   Request monitoring and tracing.

## Istio Ingress

Istio Ingress is an Istio component that manages external traffic into the service mesh.

**How It Works**

Istio Ingress acts as an entry point to the Service Mesh, handling external HTTP, HTTPS, and TCP requests and directing them to internal services via Istio.

**Key Features**

-   External traffic management.
-   Request routing.
-   Support for TLS and mTLS.

## Jaeger

Jaeger is a distributed tracing tool used for monitoring microservice interactions and analyzing their performance.

**How It Works**

Jaeger collects data on service-to-service requests, recording timestamps and dependencies. This allows for request chain tracking, latency analysis, and identifying bottlenecks in the system.

**Key Features**

-   Distributed request tracing.
-   Service response time analysis.
-   Identifying bottlenecks in architecture.

## Kiali

Kiali is a tool for managing and visualizing the Istio Service Mesh in Kubernetes.

**How It Works**

Kiali provides a graphical representation of service network interactions, displaying dependencies, metrics, and potential issues. It integrates with Prometheus to collect traffic, error, and performance data and simplifies Istio configuration management.

**Key Features**

-   Service mesh visualization.
-   Traffic and error monitoring.
-   Istio configuration management.

## Kube Prometheus Stack

Kube Prometheus Stack is a Kubernetes monitoring toolset that includes Prometheus for metrics collection, Alertmanager for alerting, and Grafana for data visualization.

**How It Works**

The system automatically collects metrics from Kubernetes components, pods, nodes, and services that support Prometheus metric export. Data is stored in Prometheus, visualized in Grafana, and Alertmanager sends notifications when predefined thresholds are exceeded.

**Key Features**

-   Metric collection and storage.
-   Data visualization in Grafana.
-   Alert configuration.

## Kubernetes Dashboard

> [!NOTE]
> The add-on is deprecated and is only available in clusters where it was previously installed.

Kubernetes Dashboard is a web interface for managing and monitoring a Kubernetes cluster.

Kubernetes Dashboard requires the Nginx Ingress add-on to function. When enabling Kubernetes Dashboard, Nginx Ingress will be automatically selected.

**How It Works**

The Dashboard provides users with a graphical interface to interact with the cluster. It allows users to view the status of pods, nodes, services, and other Kubernetes resources. The interface also supports creating, modifying, and deleting resources.

**Key Features**

-   Cluster status overview (pods, nodes, services, configurations)
-   Cluster resource management
-   Instant access to pod logs and running application information
-   Management of secrets and configurations

**Accessing Kubernetes Dashboard**

If you enable the Kubernetes Dashboard option for your cluster, you can access it from the management panel. You will need a token to log in, which can be copied from the **Information** tab on the cluster **Dashboard**.

![B8db9542 Ccc3 4e1a Bd49 4ec685bc6947](https://content.hostman.com/assets/b01b69b3-77d9-4c8e-9370-5cc5fab6df5c.png?width=1568&height=1011)

## Nginx Ingress

[Nginx Ingress](https://hostman.com/docs/kubernetes/addons/nginx-ingress/) is an Ingress controller that manages external traffic access to services within a Kubernetes cluster via HTTP and HTTPS. It routes traffic based on rules defined in Ingress resources.

**How It Works**

The Ingress controller monitors Ingress objects in Kubernetes and configures the Nginx reverse proxy to route traffic to the appropriate services. This allows access to various microservices through a single IP address, as well as setting up load balancing and routing based on domain names.

**Key Features**

-   HTTP/HTTPS request routing
-   SSL/TLS support
-   Load balancing
-   Managing external access to services in the cluster

## OpenFaaS Kubernetes

[OpenFaaS](https://hostman.com/docs/kubernetes/addons/openfaas/) is a platform for running functions (Function as a Service, FaaS) in Kubernetes. It enables fast deployment and execution of containerized functions on demand or in response to events.

**How It Works**

Functions in OpenFaaS are packaged into Docker images and deployed as pods within the cluster. The platform manages their scaling, request routing, and security.

OpenFaaS provides both a web interface and a CLI tool (faas-cli) for managing functions. It supports popular programming languages through templates, including Python, Node.js, Go, and others.

**Key Features**

-   Deployment of functions using the FaaS model in Kubernetes.
-   Web interface and CLI for managing functions.
-   Support for both built-in and custom functions.
-   Integration with Docker Hub.
-   Automatic scaling of functions based on workload.

## Traefik

[Traefik](https://hostman.com/docs/kubernetes/addons/traefik/) is an Ingress controller and load balancer for Kubernetes, providing dynamic traffic routing and automatic SSL certificate management.

**How It Works**

Traefik automatically discovers services in the cluster and configures HTTP/HTTPS traffic routing.

**Key Features**

-   Traffic routing.
-   Integration with Let's Encrypt.

## Vault

[Vault](https://hostman.com/docs/kubernetes/addons/vault/) is a secrets management system developed by HashiCorp. It allows centralized storage of tokens, passwords, certificates, and other sensitive data. In Kubernetes, it is used as an external secrets storage system with flexible access control capabilities.

**How It Works**

Vault is installed as an add-on in a cluster and can operate in either dev or HA (High Availability) mode.

-   The dev mode is intended only for development and testing.
-   The HA mode provides fault tolerance, scalability, and the use of distributed storage (for example, CSI-S3).

**Key Features**

-   Centralized and secure secret storage.
-   Support for both dev and HA modes.
-   Built-in UI for managing data.
-   Integration with Kubernetes: automatic injection of secrets into pods.
-   Support for Raft and external CSI storage backends.

## Velero

[Velero](https://hostman.com/docs/kubernetes/addons/velero/) is a tool for backup, restore, and data migration in Kubernetes.

**How It Works**

Velero allows backups and restores at the namespace, resource, and PersistentVolume levels.

**Key Features**

-   Kubernetes resource backup and restoration.
-   Data and application migration between clusters.
-   Support for local and cloud storage for backups.

## VictoriaMetrics Operator

[VictoriaMetrics Operator](https://hostman.com/docs/kubernetes/addons/victoriametrics-operator/) is a Kubernetes operator that automates the deployment and management of monitoring components based on VictoriaMetrics. It enables metric collection, storage, and visualization without the need to manually configure each component.

**How It Works**

The operator uses CRD (Custom Resource Definition) objects to manage the monitoring infrastructure:

-   **VMSingle**: a single-node instance of VictoriaMetrics, suitable for simple or testing clusters.
-   **VMCluster**: a scalable, multi-component setup designed for production environments.
-   **VMAgent**: collects metrics from pods and services and forwards them to VMSingle or VMCluster.
-   **VMPodScrape**: defines which pods to scrape and how to do it.

Metrics are collected by VMAgent, and data can be accessed through the VictoriaMetrics web interface.

**Key Features**

-   Automated installation of monitoring components.
-   Collection of metrics from pods, services, and external sources.
-   Flexible configuration of metric storage and aggregation.
-   Scalability and production-grade performance.
-   Integration with Ingress for web interface access

# cert-manager

Source: https://hostman.com/docs/kubernetes/addons/cert-manager/

`cert-manager` is an extension for Kubernetes that automates the issuance and renewal of certificates. It allows you to obtain certificates from Let's Encrypt and other certificate authorities (CAs) or use internal root certificates. `cert-manager` simplifies certificate management by automatically renewing them before expiration and ensuring secure encryption for services within the cluster. It integrates with Ingress controllers and supports various domain verification methods, making it a convenient tool for automating certificate management in Kubernetes.

## Installation

To install cert-manager:

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** section and select **cert-manager**.
3.  Click **Install** and wait for the process to complete.

To verify the installation, run the following command:

```shell
kubectl get pods -n cert-manager
```

All pods in the `cert-manager` namespace should have the status `Running`.

## Usage

To enable cert-manager to issue certificates, you need to create a `ClusterIssuer` object, which manages certificates at the cluster level.

Example manifest:

```yml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    email: email@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
```

Here:

-   `email` – Your email address, required for certificate issuance. Let's Encrypt will send notifications to this address.
-   `server` – The URL of Let's Encrypt or another certificate authority.
-   `privateKeySecretRef` – The secret that stores the private key.
-   `solvers.http01.ingress.class` – The method for verifying domain ownership via HTTP, using the Nginx Ingress controller in this case.

If you're using a different Ingress controller, replace `nginx` with the appropriate value. For example, for Traefik:

```yml
solvers:
  - http01:
      ingress:
        class: traefik
```

## Example Usage of cert-manager

Let's consider an example where `cert-manager` is used with resources from our [Nginx Ingress](https://hostman.com/docs/kubernetes/addons/nginx-ingress/) setup.

If you followed our guide, you have already set up:

-   Three deployments
-   Nginx Ingress
-   A LoadBalancer

Your services are accessible via:

-   `http://ingress1.example.com/service1`
-   `http://ingress1.example.com/service2`
-   `http://ingress2.example.com/`

Now we need to define a `ClusterIssuer` in a file named `cluster-issuer.yaml`:

```yml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    email: email@example.com
    server: https://acme-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
```

Apply the manifest:

```shell
kubectl apply -f cluster-issuer.yaml
```

Next, you need to update the `Ingress` resource. Modify the existing Ingress manifest by adding an annotation for `cert-manager` and a `tls` section.

Updated `ingress.yaml`:

```yml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: ingress-example
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  rules:
  - host: ingress1.example.com
    http:
      paths:
      - path: /service1
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 80
      - path: /service2
        pathType: Prefix
        backend:
          service:
            name: service2
            port:
              number: 80
  tls:
  - hosts:
    - ingress1.example.com
    secretName: ingress-tls
```

Changes in this manifest:

1.  Added the annotation `cert-manager.io/cluster-issuer: letsencrypt-prod` to instruct cert-manager to use the created `ClusterIssuer`.
    
2.  Added the `tls` section, specifying the domains for which cert-manager should issue certificates and the secret (`ingress-tls`) where they will be stored.
    

Apply the updated manifest:

```shell
kubectl apply -f ingress.yaml
```

After a short period, cert-manager will issue the certificates and store them in the `ingress-tls` secret. To check the certificates, use:

```shell
kubectl get secret ingress-tls -n ingress-example -o yaml
```

If successful, the secret should contain `tls.crt` and `tls.key`.

Run the following command to test HTTPS connectivity:

```shell
curl -v https://ingress1.example.com/service1
```

If the request completes without errors, the certificates are successfully installed, and the services are running over HTTPS.

# cert-manager CSI Driver

Source: https://hostman.com/docs/kubernetes/addons/cert-manager-csi-driver/

cert-manager CSI Driver is a Kubernetes add-on that mounts TLS certificates directly into pods. It works alongside [cert-manager](https://hostman.com/docs/kubernetes/addons/cert-manager/): you define certificate parameters in the pod manifest, and the driver requests a certificate and mounts it—along with its private key—into the specified directory. There's no need to create a separate Certificate resource or secret for the pod's certificate.

## How It Works

This approach works well for applications that handle TLS connections themselves and read certificates from files. For example, the driver can issue and mount a certificate for an Nginx pod, or give each pod its own certificate for mutual authentication between services. Certificates are issued through a configured `Issuer` or `ClusterIssuer`, including Let's Encrypt.

Each application replica gets its own certificate and key. The private key is generated on the node running the pod, stays in memory, and is never transmitted over the network by the driver. When a pod is deleted, its certificate files are removed; when the pod is recreated, a new certificate is issued.

If you need a certificate to persist across pod recreations, or to use for HTTPS on an Ingress controller, configure it through cert-manager with a `Certificate` resource and a secret instead.

## Install cert-manager CSI Driver

[cert-manager](https://hostman.com/docs/kubernetes/addons/cert-manager/) must already be installed in the cluster before you install this add-on.

1.  Go to the **Kubernetes** section and select your cluster.
2.  Open the **Addons** tab and click **cert-manager CSI Driver**.
3.  In the setup wizard, click **Install** and wait for the installation to complete.

## Verify the Installation

Connect to the cluster [with kubectl](https://hostman.com/docs/kubernetes/connect-to-clusters/kubectl/) and check that the driver is registered:

```shell
kubectl get csidriver csi.cert-manager.io
```

The output should list the `csi.cert-manager.io` driver with `Ephemeral` mode. This mode is used for temporary volumes tied to a pod's lifecycle, so you don't need to create a `StorageClass`, `PersistentVolume`, or `PersistentVolumeClaim` for them.

The driver runs on worker nodes as a `DaemonSet`. Check its status with:

```shell
kubectl get daemonsets -A
```

Find the cert-manager CSI Driver `DaemonSet` in the list. The values in the `DESIRED` and `READY` columns should match and be greater than zero.

# Cluster Proportional Autoscaler

Source: https://hostman.com/docs/kubernetes/addons/cpa/

Cluster Proportional Autoscaler (CPA) is a controller that automatically scales a specified deployment based on the number of nodes in the cluster. It is especially useful when a service needs to be available on every node or should scale proportionally to the overall cluster resources.

Unlike traditional autoscalers, CPA does not rely on load metrics. Instead, it uses proportional formulas that are manually defined.

## Modes of Operation

CPA supports two modes for calculating the number of replicas:

### Linear Mode

In linear mode, the number of replicas is calculated using the following formula:

```shell
replicas = max(min, min(max, cores / coresPerReplica, nodes / nodesPerReplica))
```

You can use both parameters (coresPerReplica and nodesPerReplica) or just one. The min and max values set the lower and upper limits for the number of replicas.

Example configuration:

```shell
config:
  linear:
    coresPerReplica: 2
    nodesPerReplica: 1
    min: 2
    max: 20
    preventSinglePointFailure: true
    includeUnschedulableNodes: true
```

In this example:

-   One pod is created per node
-   An additional pod is created for every 2 CPU cores
-   Always at least 2 pods, maximum 20
-   If there's only one node, 2 pods will be created to prevent a single point of failure
-   Unschedulable nodes are also taken into account

### Ladder Mode

In ladder mode, the number of replicas is explicitly defined using a lookup table. This is useful when you need an exact number of pods for specific cluster sizes.

Example configuration:

```shell
config:
  ladder:
    coresToReplicas:
      - [ 1, 1 ]
      - [ 64, 3 ]
      - [ 512, 5 ]
      - [ 1024, 7 ]
      - [ 2048, 10 ]
    nodesToReplicas:
      - [ 1, 1 ]
      - [ 2, 2 ]
      - [ 5, 3 ]
```

In this example:

-   With 1 node → 1 pod
-   With 2 nodes → 2 pods
-   With 5 or more nodes → 3 pods
-   CPU cores are also considered in parallel:
    -   64 cores → 3 pods
    -   2048 cores → 10 pods

## Installation via Dashboard

To install Cluster Proportional Autoscaler:

1.  Go to the **Kubernetes** section and click on the cluster.
2.  In the **Addons** tab, click on **Cluster Proportional Autoscaler**.
3.  In the installation wizard, you can adjust the configuration by editing the manifest in the **Configuration** section.

By default, the autoscaler is configured to scale the `metrics-server` in the `kube-system` namespace using linear mode, creating one pod per node:

```shell
config:
  linear:
    coresPerReplica: 1
    nodesPerReplica: 1
    min: 1
    max: 100
    preventSinglePointFailure: true
    includeUnschedulableNodes: true

options:
  logToStdErr: true
  logLevel: 7
  namespace: kube-system
  target: deployment/metrics-server
```

If you want to scale a different service—for example, `nginx` in the `default` namespace—change the `target` and `namespace` parameters before installing.

To switch scaling modes or parameters, edit the `config` section. For instance, you can uncomment the `ladder` parameters and use that mode instead of `linear`.

> [!NOTE]
> When installing via the web UI, only one target resource can be specified using the `target` parameter.
>
> If you want to scale multiple resources—such as both `metrics-server` and `coredns`—you need to use manual installation with multiple autoscaler instances.

## Manual Installation

If you need more flexibility or want to deploy multiple autoscalers for different services, use [Helm](https://hostman.com/docs/kubernetes/helm/) for installation.

**Step 1:** Add the Helm chart repository:

```shell
helm repo add cluster-proportional-autoscaler https://kubernetes-sigs.github.io/cluster-proportional-autoscaler
```

This adds an external source from which the autoscaler can be installed.

**Step 2:** Update chart list:

```shell
helm repo update
```

**Step 3:** Create a `values.yaml` file with the following content:

```shell
config:
  linear:
    coresPerReplica: 1
    nodesPerReplica: 1
    min: 1
    max: 100
    preventSinglePointFailure: true
    includeUnschedulableNodes: true

options:
  logToStdErr: true
  logLevel: 7
  namespace: kube-system
  target: deployment/metrics-server

serviceAccount:
  create: true
```

This configuration:

-   Uses linear mode, creating one pod per node (`nodesPerReplica: 1`)
-   Limits replicas between 1 and 100
-   Enables `preventSinglePointFailure` (adds an extra pod if only one node exists)
-   Includes unschedulable nodes in calculations
-   Specifies the target deployment and namespace
-   Automatically creates a service account with the required permissions

**Step 4:** Install the autoscaler with Helm:

```shell
helm upgrade --install metrics-autoscaler cluster-proportional-autoscaler/cluster-proportional-autoscaler --values values.yaml
```

**Step 5:** Verify the pod is running:

```shell
kubectl get pods -n kube-system
```

## Scaling Multiple Services

With manual installation, you can run multiple independent autoscaler instances for different services.

To do so:

1.  Create a separate `values-nginx.yaml` file
2.  Update the `target` and `namespace` parameters for the deployment (e.g., `nginx` in the `default` namespace)
3.  Install using a different release name:

```shell
helm upgrade --install nginx-autoscaler cluster-proportional-autoscaler/cluster-proportional-autoscaler --values values-nginx.yaml
```

This method allows you to scale any number of services with individual settings.

# CSI S3

Source: https://hostman.com/docs/kubernetes/addons/csi-s3/

Integrating S3 into Kubernetes allows applications to interact with object storage as if it were a traditional file system. In Hostman, this is achieved using CSI S3 (Container Storage Interface), enabling seamless connection of S3 buckets to Kubernetes pods. Below is a step-by-step guide to setting up and using CSI S3 in a Kubernetes cluster.

## Installing CSI S3

Follow these steps to install CSI S3:

1.  Go to the Kubernetes section and click on the cluster.
2.  Open the **Addons** tab.
3.  Click the three dots next to the **CSI S3** add-on and select **Install**.
4.  Select an existing S3 bucket, create a new one, or connect an external S3 bucket.
5.  Click **Install** and wait for the process to complete.

Once installed, the bucket will be available for use in the cluster without requiring additional configuration.

## Verifying Installation

To ensure CSI S3 is successfully installed and connected, run the following commands:

-   To check the `StorageClass`:
    

```shell
kubectl get storageclass csi-s3 -o yaml
```

-   To view S3 connection details:

```shell
kubectl get secret csi-s3-secret -n csi-s3 -o yaml
```

The connection details will appear in the data section in Base64 format.

## Using CSI S3 in Kubernetes

Since S3 is an object storage system, Kubernetes cannot directly interact with it. [Kubernetes](https://hostman.com/products/kubernetes/) uses file systems and block devices, so a `PersistentVolumeClaim` (PVC) is used to bridge the gap via the CSI driver. A FUSE layer, such as `geesefs`, is used to mount the S3 bucket and make files accessible as a typical file system.

> [!NOTE]
> Note that CSI S3 is not a full POSIX-compliant file system. It is best suited for storing static files like images, CSS, JS, configuration files, or other data that does not require intensive disk operations. Issues may arise hosting databases or other applications that modify file permissions or ownership.
>
> Partial file overwrites and creating hard links (hardlinks) are not supported.

#### PersistentVolumeClaim (PVC)

PVC acts as a "request" for storage. Kubernetes responds to the request by creating a `PersistentVolume` (PV), which links to the PVC and provides access to storage.

Below is an example PVC manifest for connecting to S3:

```yml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: csi-s3-pvc
  namespace: default
spec:
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 5Gi
  storageClassName: csi-s3
```

**Key parameters in the PVC manifest:**

-   `apiVersion` and `kind`: Defines the resource as a `PersistentVolumeClaim` (version v1).
-   `metadata`: Specifies the PVC name (`csi-s3-pvc`) and the namespace (`default`).
-   `accessModes`: Specifies the storage access mode. `ReadWriteMany` allows multiple pods to read/write to the same storage.
-   `resources.requests.storage`: Requests 5 GiB of storage space for the application.
-   `storageClassName`: Indicates the `StorageClass` name (`csi-s3`).

## Connecting PVC to a Deployment

To enable an application to use a `PersistentVolumeClaim` (PVC), you need to configure it in the `Deployment` manifest. Below is an example showing how an Nginx container uses a connected PVC:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: s3-app-deployment
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: s3-app
  template:
    metadata:
      labels:
        app: s3-app
    spec:
      containers:
        - name: s3-app-container
          image: nginx
          volumeMounts:
            - name: s3-storage
              mountPath: /usr/share/nginx/html
      volumes:
        - name: s3-storage
          persistentVolumeClaim:
            claimName: csi-s3-pvc
```

**Key elements of the Deployment manifest:**

-   `apiVersion` and `kind`: Specifies that the resource is a `Deployment` of version apps/v1.
-   `metadata`: Defines the `Deployment` name (`s3-app-deployment`) and the namespace (`default`).
-   `replicas`: Specifies the number of replicas (1 in this example), enabling application scaling.
-   `template`: Contains the pod specification for the `Deployment`.
-   `containers`: Describes the containers included in the pod. In this example, the pod includes a container running the Nginx image.
-   `volumeMounts`: Defines the volume mount point inside the container. Here, the PVC is mounted to `/usr/share/nginx/html`, allowing the container to access data stored in S3 through the volume.
-   `volumes`: Specifies the volumes used by the pod. The volume `s3-storage` is linked to the PVC named `csi-s3-pvc`, ensuring that data from S3 is accessible through this volume.

Using PVC allows an application to access data in S3 and also simplifies access control and scaling by ensuring that each replica has access to shared data.

# Envoy Gateway

Source: https://hostman.com/docs/kubernetes/addons/envoy-gateway/

Envoy Gateway is a Kubernetes Gateway API controller that uses Envoy Proxy to handle incoming traffic. You can use it to publish HTTP, HTTPS, gRPC, TCP, and UDP services, configure routing by domain and path, manage TLS, and apply traffic policies using standard Kubernetes resources.

Gateway API is the evolution of Ingress. Instead of a single Ingress resource, it splits responsibilities across several dedicated objects:

-   `GatewayClass` defines which controller will manage the gateways.
-   `Gateway` describes the entry point: ports, protocols, and TLS settings.
-   `HTTPRoute` defines HTTP traffic routing rules to backend services.
-   `GRPCRoute`, `TCPRoute`, `UDPRoute`, `TLSRoute` handle other traffic types.

Envoy Gateway watches these resources and uses them to create an Envoy Proxy that accepts external traffic and routes it to services inside the cluster.

## Installation

To install Envoy Gateway:

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** tab and select **Envoy Gateway**.
3.  (Optional) Enable **Advanced setup** to edit `values.yaml`. For most use cases, the defaults are a good starting point.
4.  Click **Install**.
5.  Wait for the process to complete and verify that the Envoy Gateway pods are running:

```shell
kubectl get pods -n envoy-gateway-system
```

All pods should show a `Running` status.

You can also confirm that the Gateway API resources are available in the cluster:

```shell
kubectl api-resources | grep gateway.networking.k8s.io
```

## Usage Example

This example shows how to configure Envoy Gateway to accept HTTP traffic on a single external IP and route requests to two different services:

-   `http://app.example.com/service1 routes to service1`
-   `http://app.example.com/service2 routes to service2`

Start by creating a dedicated namespace:

```shell
kubectl create namespace envoy-example
```

### Create a ConfigMap

Create a file called `configmap.yaml` with HTML pages for both services:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-pages
  namespace: envoy-example
data:
  service1.html: |
    <html>
      <head><title>Service 1</title></head>
      <body><h1>Service 1</h1></body>
    </html>
  service2.html: |
    <html>
      <head><title>Service 2</title></head>
      <body><h1>Service 2</h1></body>
    </html>
```

Apply the manifest:

```shell
kubectl apply -f configmap.yaml
```

### Create Deployments and Services

Create `service1.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service1
  namespace: envoy-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service1
  template:
    metadata:
      labels:
        app: service1
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80
          volumeMounts:
            - name: html
              mountPath: /usr/share/nginx/html
      volumes:
        - name: html
          configMap:
            name: nginx-pages
            items:
              - key: service1.html
                path: index.html
---
apiVersion: v1
kind: Service
metadata:
  name: service1
  namespace: envoy-example
spec:
  selector:
    app: service1
  ports:
    - name: http
      port: 80
      targetPort: 80
  type: ClusterIP
```

Create `service2.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service2
  namespace: envoy-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service2
  template:
    metadata:
      labels:
        app: service2
    spec:
      containers:
        - name: nginx
          image: nginx:latest
          ports:
            - containerPort: 80
          volumeMounts:
            - name: html
              mountPath: /usr/share/nginx/html
      volumes:
        - name: html
          configMap:
            name: nginx-pages
            items:
              - key: service2.html
                path: index.html
---
apiVersion: v1
kind: Service
metadata:
  name: service2
  namespace: envoy-example
spec:
  selector:
    app: service2
  ports:
    - name: http
      port: 80
      targetPort: 80
  type: ClusterIP
```

Apply both manifests:

```shell
kubectl apply -f service1.yaml
kubectl apply -f service2.yaml
```

Verify the pods are running:

```shell
kubectl get pods -n envoy-example
```

### Create a GatewayClass

`GatewayClass` connects the Gateway API to the Envoy Gateway controller.

Create `gatewayclass.yaml`:

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy-gateway
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
```

Apply it:

```shell
kubectl apply -f gatewayclass.yaml
```

Check the status:

```shell
kubectl get gatewayclass envoy-gateway
```

The `ACCEPTED` column should show `True`, which means Envoy Gateway has registered the `GatewayClass` and will manage resources associated with it.

### Create a Gateway

The `Gateway` resource defines the external entry point for your application.

Create `gateway.yaml`:

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: app-gateway
  namespace: envoy-example
spec:
  gatewayClassName: envoy-gateway
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same
```

Apply it:

```shell
kubectl apply -f gateway.yaml
```

Once the `Gateway` is created, Envoy Gateway will provision an Envoy Proxy and a load balancer. You can track the load balancer creation in the [Hostman dashboard](https://hostman.com/my/balancer), or run:

```shell
kubectl get gateway app-gateway -n envoy-example
```

Wait until `PROGRAMMED` shows `True` and `ADDRESS` shows an external IP.

You can also inspect the service that was created:

```shell
kubectl get svc -n envoy-gateway-system \
  -l gateway.envoyproxy.io/owning-gateway-namespace=envoy-example,gateway.envoyproxy.io/owning-gateway-name=app-gateway
```

> [!NOTE]
> **Note**: Envoy Gateway automatically creates a `LoadBalancer` service for each `Gateway`, so you don't need to create a separate `Service` manifest as you would with a classic Ingress controller setup.

### Create an HTTPRoute

`HTTPRoute` defines the routing rules.

Create `httproute.yaml`:

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: app-route
  namespace: envoy-example
spec:
  parentRefs:
    - name: app-gateway
  hostnames:
    - app.example.com
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /service1
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: service1
          port: 80
    - matches:
        - path:
            type: PathPrefix
            value: /service2
      filters:
        - type: URLRewrite
          urlRewrite:
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /
      backendRefs:
        - name: service2
          port: 80
```

Apply it:

```shell
kubectl apply -f httproute.yaml
```

Confirm the route is accepted:

```shell
kubectl get httproute app-route -n envoy-example -o yaml
```

The resource status should include:

```shell
status: "True" type: Accepted
```

This `HTTPRoute` accepts requests for `app.example.com` and routes them to different services based on the path prefix. The `URLRewrite` filter strips the `/service1` and `/service2` prefixes, replacing them with `/`, so Nginx inside each service serves its main page correctly.

### Verify the Setup

Get the external IP of the Gateway:

```shell
kubectl get gateway app-gateway -n envoy-example
```

Add this IP as an A record for app.example.com in your DNS settings. Once DNS propagates, test both endpoints:

```shell
curl http://app.example.com/service1
curl http://app.example.com/service2
```

If DNS hasn't propagated yet, you can test by IP using the `Host` header:

```shell
curl -H "Host: app.example.com" http://<EXTERNAL_IP>/service1
curl -H "Host: app.example.com" http://<EXTERNAL_IP>/service2
```

Both requests should return the respective Service 1 and Service 2 pages.

### Clean Up

To remove all resources created in this example, run:

```shell
kubectl delete namespace envoy-example
kubectl delete gatewayclass envoy-gateway
```

This does not uninstall the Envoy Gateway add-on. To remove it, go to the **Addons** tab in the cluster dashboard.

## Migrating from Nginx Ingress to Envoy Gateway

You can run Envoy Gateway alongside Nginx Ingress and migrate routes gradually. This lets you test Gateway API resources on a separate external IP before switching DNS records or redirecting traffic to the new Gateway.

To automate the conversion of existing Ingress resources, use the [ingress2gateway](https://github.com/kubernetes-sigs/ingress2gateway) utility. It reads Ingress resources from your cluster and outputs equivalent Gateway API resources: `Gateway`, `HTTPRoute`, and related objects.

> [!NOTE]
> **Important**: `ingress2gateway` is a helpful starting point, but it is not a fully automatic migration tool. Some Nginx Ingress annotations may not be supported or may require manual configuration after conversion.

### Prerequisites

Before migrating, make sure your cluster is ready:

-   Envoy Gateway is installed.
-   A `GatewayClass` for Envoy Gateway has been created.
-   Existing Ingress resources are working correctly through Nginx Ingress.

Check that both classes are present:

```shell
kubectl get ingressclass
kubectl get gatewayclass
```

The output should include an `IngressClass` named `nginx` and a `GatewayClass` named `envoy-gateway`.

### Install ingress2gateway

If you have Go installed locally, run:

```shell
go install github.com/kubernetes-sigs/ingress2gateway@v1.0.0
```

The binary will be placed in `$(go env GOPATH)/bin`. Make sure this directory is in your `PATH`.

Alternatively, install via Homebrew:

```shell
brew install ingress2gateway
```

Or download a prebuilt binary from the [project releases page](https://github.com/kubernetes-sigs/ingress2gateway/releases).

### Source Setup

In this example, the migration targets an application already published through Nginx Ingress.

The cluster has a namespace called `ingress-migration-demo` containing:

-   An Ingress resource named `migration-source`
-   Services `service1` and `service2`
-   Two routing rules for the domain `ingress-migration.example.com`:
    -   `/service1` routes to `service1`
    -   `/service2` routes to `service2`

Verify the source Ingress:

```shell
kubectl get ingress -n ingress-migration-demo
```

The `CLASS` column should show `nginx`.

### Convert Ingress Resources

To convert the Ingress to Gateway API resources, run:

```shell
ingress2gateway print \
 --providers=ingress-nginx \
 --emitter=envoy-gateway \
 --ingress-nginx-ingress-class=nginx \
 --namespace=ingress-migration-demo > gateway-migration.yaml
```

The flags in this command:

-   `print` outputs the generated resources to stdout; the `>` redirect saves them to `gateway-migration.yaml`.
-   `--providers=ingress-nginx` specifies the source Ingress controller type.
-   `--emitter=envoy-gateway` sets Envoy Gateway as the target controller.
-   `--ingress-nginx-ingress-class=nginx` filters for Ingress resources using the `nginx` class.
-   `--namespace=ingress-migration-demo` scopes the conversion to the source namespace.

### Review and Fix the Output

Open `gateway-migration.yaml` and review the generated resources before applying them.

Pay attention to the `gatewayClassName` field in the `Gateway` resource. The tool may generate this value based on the source `IngressClass` name, resulting in something like:

```yaml
spec:
  gatewayClassName: nginx
```

Envoy Gateway will not process a `Gateway` with this class name unless a `GatewayClass` named `nginx` exists in the cluster. Update it to match the `GatewayClass` you created earlier:

```yaml
spec:
  gatewayClassName: envoy-gateway
```

### Apply the Gateway API Resources

Once you're satisfied with the output, apply it:

```shell
kubectl apply -f gateway-migration.yaml
```

Verify the `Gateway` has been created and has received an external IP:

```shell
kubectl get gateway -A
```

Check that the `HTTPRoute` has been accepted by the controller:

```shell
kubectl get httproute -A
kubectl describe httproute <route-name> -n <namespace>
```

The `HTTPRoute` status should show both `Accepted=True` and `ResolvedRefs=True`.

### Test Before Switching Traffic

While your DNS records still point to the old Nginx Ingress, you can verify the new `Gateway` by sending requests directly to its external IP with a `Host` header:

```shell
curl -H "Host: app.example.com" http://<EXTERNAL_IP>/<path>
```

Where:

-   `app.example.com` is the domain from your `HTTPRoute`.
-   `<EXTERNAL_IP>` is the IP address of the new `Gateway`.
-   `<path>` is the path handled by the route.

Compare the responses from the old Ingress and the new `Gateway`. If everything looks correct, update your DNS records to point to the new load balancer's IP.

# Fluent Operator

Source: https://hostman.com/docs/kubernetes/addons/fluent-operator/

In Kubernetes clusters, applications and system services generate a large number of logs. To facilitate analysis and storage of these logs, they can be collected in systems such as Elasticsearch, Loki, Kafka, Prometheus, and others.

Fluent Bit and Fluentd are tools for log collection and processing. However, configuring them in Kubernetes can be complex:

-   Manually creating resources (DaemonSet, StatefulSet) is required.
-   Configuration files need to be set up.
-   Container runtime specifics must be considered.
-   Secrets must be managed for authentication.
-   Updates and compatibility need to be monitored.

Fluent Operator simplifies this process by:

-   Automating the deployment of Fluent Bit and Fluentd, creating the necessary resources.
-   Using Custom Resource Definitions (CRD) to configure inputs, filters, outputs, and other parameters via YAML manifests.
-   Managing updates and scaling of Fluent Bit/Fluentd in response to cluster changes.
-   Simplifying integration with Elasticsearch, Loki, Kafka, Prometheus, and others.

Instead of manually configuring Fluent Bit and Fluentd, you install Fluent Operator and describe the settings. The operator brings the cluster to the desired state and automatically updates the agents when the configuration changes.

**Main Components**

-   **Fluent Bit**: A lightweight log collection agent.
-   **Fluentd**: A powerful agent that can be used as a DaemonSet or StatefulSet for advanced filtering and buffering.
-   **Fluent Operator**: Manages Fluent Bit and Fluentd through CRDs.

## Installation

You can install Fluent Operator via the Hostman dashboard:

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** tab and select **Fluent Operator**.
3.  Enable **Advanced setup** and adjust the configuration for your needs.
4.  Click **Install**.

## Installation Parameters

### Operator

The `operator` section:

-   `containerRuntime`: Defines the container runtime used. In our managed Kubernetes, containerd is used. This value does not need to be changed.
-   `logPath`: Log file path. For containerd, it is `/var/log`.
-   `disableComponentControllers`: A list of Fluent Operator components to disable. Possible values: `fluent-bit` and `fluentd`. By default, both components are installed.

### Fluent Bit

The `input` section:

-   **tail**:
    -   `enable: true` — Enables log collection from files located at `/var/log/containers/*.log`.
    -   `path: "/var/log/containers/*.log"` — Defines the path to container log files.
    -   `refreshIntervalSeconds: 10` — The frequency (in seconds) for refreshing the log file list.
    -   `memBufLimit: 100MB` — Memory limit for buffering.
    -   `storageType: memory` — Storage type for the buffer. An alternative is filesystem, but a volume must be prepared in advance.
    -   `readFromHead: false` — Starts reading logs from the end.
    -   `skipLongLines: true` — Skips excessively long lines.
-   **systemd**:
    -   `enable: true` — Enables log collection from `journald`.
    -   `includeKubelet: true` — Includes kubelet logs from `journald`.
    -   `storageType: memory` — Sets the storage type for `journald` log buffers.

The `output` section:

Lists the main output options. To enable each one, set `enable: true` and specify the parameters:

-   **Elasticsearch**

```yml
  es:
    enable: false
    host: "<Elasticsearch url>"
    port: 9200
    logstashPrefix: ks-logstash-log
    bufferSize: 20MB
    traceError: true
    httpUser: "<username>"
    httpPassword: "<password>"
```

Configuration for sending logs to Elasticsearch. Specify the service URL, port, and authentication credentials.

-   **Kafka**

```yml
  kafka:
    enable: false
    brokers: "<kafka broker list>"
    topics: ks-log
    bufferSize: 20MB
    retryLimit: "10"
```

Configuration for sending logs to Kafka. Specify a comma-separated list of brokers and the topic for logs.

-   **Loki**

```yml
  loki:
    enable: false
    retryLimit: "no_limits"
    host: 127.0.0.1
    port: 3100
    httpUser: myuser
    httpPassword: mypass
    tenantId: "<tenant>"
```

Allows sending logs to Loki. Specify the host, port, credentials, and tenant ID.

-   **stdout**

```yml
  stdout:
    enable: true
```

Useful for testing, as it outputs logs to standard output (stdout).

The `filter` section:

-   **multiline**:
    -   `enable: false` — By default, multiline is disabled.
    -   You can configure parsers (`go`, `python`, `java`, etc.) or add custom ones.
-   **kubernetes**:
    -   `enable: true` — Enables the Kubernetes filter to add pod metadata, such as `namespace`, `pod`, `labels`, and `annotations`.
    -   `labels: false`, `annotations: false` — By default, these fields are not added.
-   **containerd**:
    -   `enable: true` — Enables the filter for parsing Containerd logs.
-   **systemd**:
    -   `enable: true` — Enables the filter for parsing `journald` logs.

### Fluentd

-   **enable** — If you need to use Fluentd (instead of or alongside Fluent Bit), set it to true.
-   **mode**:
    -   `collector` — Deploys as a StatefulSet.
    -   `agent` — Deploys as a DaemonSet (like Fluent Bit), meaning one agent per node.
-   **forward**:
    -   `port: 24224` — The default Fluentd input for forwarding.
-   **output** — Similar to Fluent Bit, it includes `es`, `kafka`, `opensearch`, etc.

## Removing Fluent Operator

Uninstalling the add-on via the management panel is not supported, but it can be done manually. Follow these steps:

1.  Delete the `fluent-bit` object:
    

```shell
kubectl delete -n fluent-operator fluentbit/fluent-bit
```

2.  Uninstall the `fluent-operator` Helm release:
    

```shell
helm uninstall -n fluent-operator fluent-operator
```

3.  Delete all CRDs related to `fluent-operator`:
    

```shell
kubectl delete crd $(kubectl get crd | grep fluent | awk '{print $1}')
```

4.  Check that all related resources and namespaces are removed:
    

```shell
kubectl get namespaces
```

After completing these steps, Fluent Operator will be completely removed from your cluster.

# Grafana Loki

Source: https://hostman.com/docs/kubernetes/addons/grafana-loki/

Grafana Loki is a log aggregation system developed by the team at Grafana Labs. It is used in conjunction with Grafana to provide convenient log visualization.

Unlike the ELK stack, Loki does not index log content, but stores logs alongside metadata (e.g., pod name or namespace). This makes it faster and less resource-intensive.

Loki is most commonly used together with Promtail—an agent that collects logs from nodes and sends them to Loki. You can then view those logs directly in Grafana using LogQL queries.

## Installation

To install Loki:

1.  Go to the **Kubernetes** section and click on the cluster.
2.  In the **Addons** tab, click on **Grafana Loki**.
3.  You'll see a YAML configuration with default parameters.

![0c66a302 86f1 478c A370 0024a7ffd1fa](https://content.hostman.com/assets/dfe93116-ebcb-489c-b55a-cd047a982f01.png?width=1522&height=981)

Here’s a brief explanation of each block:

```yaml
test_pod:
  enabled: true
  image: bats/bats:1.8.2
```

Launches a test pod with the bats utility to verify that Loki is available and receiving logs. Used only for automatic validation after installation.

```yaml
loki:
  enabled: true
  isDefault: true
```

The main component is Loki that is responsible for receiving and storing logs.

Configurable options include:

-   `url`: internal service address for Loki (used by other components)
-   `readinessProbe` and `livenessProbe`: health checks
-   `datasource`: settings for connecting Loki as a data source in Grafana.

You can specify `datasource.uid` if you want to link it explicitly.

```yaml
promtail:
  enabled: true
  config:
    clients:
      - url: http://<release-name>:3100/loki/api/v1/push
```

Promtail is the default agent that collects logs from cluster nodes (from `/var/log/containers/*.log`) and sends them to Loki.

If you're using alternative log shippers like Filebeat or Fluent Bit, you can disable Promtail:

```yaml
fluent-bit:
  enabled: false

filebeat:
  enabled: false
  filebeatConfig: ...

logstash:
  enabled: false
  filters: ...
  outputs: ...
```

These are optional alternatives in case Promtail isn’t suitable—for example, if you're using [Fluent Operator](https://hostman.com/docs/kubernetes/addons/fluent-operator/). They're disabled by default.

```yaml
grafana:
  enabled: false
```

Enables installation of Grafana. Set to `true` if you want to view logs through a web UI. If Grafana is already deployed in your cluster, you can leave this disabled and manually configure Loki as a data source.

```yaml
prometheus:
  enabled: false
  isDefault: false
  url: ...
```

Lets you add Prometheus as a data source in Grafana. This does not install Prometheus itself—it only registers the connection. Enable if Prometheus is already running in your cluster and you want to use it alongside Loki.

```yaml
proxy:
  http_proxy: ""
  https_proxy: ""
  no_proxy: ""
```

Proxy settings in case you need to connect to external services.

## Example Usage

Let’s walk through an example setup using Loki and Promtail.

We'll launch a pod that writes logs to standard output. Kubelet will save those logs to `/var/log/containers/`. Promtail (as a DaemonSet) reads those logs and pushes them to Loki. Then, Grafana can be used to explore them via the web interface.

### Step 1. Enable Grafana

Install the Loki addon from the cluster management panel. In the configuration window, leave all parameters as-is, but change:

```yaml
grafana: 
  enabled: false
```

to:

```yaml
grafana: 
  enabled: true
```

This will deploy Grafana along with Loki.

### Step 2. Install NGINX Ingress

Install the [NGINX Ingress](https://hostman.com/docs/kubernetes/addons/nginx-ingress/) add-on, which is required to access the Grafana interface via domain name.

### Step 3. Verify Pod Status

Run:

```shell
kubectl get pods -n loki
```

Expected output:

```shell
NAME                                 READY   STATUS    RESTARTS   AGE
loki-stack-0                         1/1     Running   0          3h5m
loki-stack-grafana-878d56dc6-s28sq   2/2     Running   0          3h5m
loki-stack-promtail-5wtlr            1/1     Running   0          3h5m
loki-stack-promtail-hl6pl            1/1     Running   0          3h5m
```

Also verify the Ingress controller is running:

```shell
kubectl get pods -n ingress-nginx
```

And check Grafana Loki services:

```shell
kubectl get svc -n loki
```

Example output:

```shell
NAME                    TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
loki-stack              ClusterIP   10.111.63.222    <none>        3100/TCP   3h7m
loki-stack-grafana      ClusterIP   10.104.154.158   <none>        80/TCP     3h7m
loki-stack-headless     ClusterIP   None             <none>        3100/TCP   3h7m
loki-stack-memberlist   ClusterIP   None             <none>        7946/TCP   3h7m
```

### Step 4. Configure Ingress

Now let’s configure NGINX Ingress to expose Grafana by domain. For this, we will create a [load balancer](https://hostman.com/docs/kubernetes/load-balancing/) and the `loadbalancer.yaml` manifest:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: ingress-nginx
  namespace: ingress-nginx
spec:
  selector:
    app.kubernetes.io/name: ingress-nginx
  ports:
    - name: http
      port: 80
      targetPort: 80
    - name: https
      port: 443
      targetPort: 443
  type: LoadBalancer
```

Apply it:

```shell
kubectl apply -f loadbalancer.yaml
```

Create an Ingress rule in the `grafana-ingress.yaml` file:

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grafana
  namespace: loki
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - host: grafana.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: loki-stack-grafana
                port:
                  number: 80
```

Replace `grafana.example.com` with your actual domain name. Make sure the domain's A record points to the LoadBalancer's external IP.

Apply the manifest:

```shell
kubectl apply -f grafana-ingress.yaml
```

### Step 5. Generate Logs

Create a pod that continuously logs messages:

```shell
kubectl run logger --image=busybox --restart=Never -- sh -c 'while true; do echo "hello from logger"; sleep 5; done'
```

Verify it's running:

```shell
kubectl get pods
```

The `logger` pod should be in `Running` state.

### Step 6. Open Grafana

Open the domain configured in your Ingress (e.g., `https://grafana.example.com`). You'll be greeted with the Grafana login screen.

Use the username `admin`. Retrieve the password with:

```shell
kubectl get secret -n loki loki-stack-grafana -o jsonpath="{.data.admin-password}" | base64 --decode
```

### Step 7. View Logs

In the Grafana UI, go to the **Explore** section:

![Fb7fe9a5 D27a 493a B0d3 143bf0fc39d7.png](https://content.hostman.com/assets/f9ee38ab-d5cb-4711-bac7-66c4d1bb10ca.png?width=2884&height=1562)

_[Grafana](https://grafana.com/) interface_

Select **Loki** as the data source. In **Label** filters, enter **pod=logger**, and click **Run query**.

![95f8c71a 1a12 467d 8f0a Acbc4d23f752.png](https://content.hostman.com/assets/f499f75d-c6b9-45fb-a5f8-a9f91b018970.png?width=2858&height=1364)

_Explore section in the [Grafana](https://grafana.com/) interface_

Scroll down, and you should see log entries like "hello from logger".

![373ffcef 2c0e 453f 9bdf 6dcd46366ed8.png](https://content.hostman.com/assets/59b4d347-4d74-4fb9-ae5e-7ce8b592d00f.png?width=2880&height=1608)

_Log entries in the [Grafana](https://grafana.com/) interface_

# Headlamp

Source: https://hostman.com/docs/kubernetes/addons/headlamp/

Headlamp is a web-based interface for managing a cluster. It allows you to view cluster resources, manage them, and monitor application status without using [kubectl](https://hostman.com/docs/kubernetes/connect-to-clusters/kubectl/).

## Installation

> [!NOTE]
> Before installing the add-on, make sure that [Nginx Ingress](https://hostman.com/docs/kubernetes/addons/nginx-ingress/) is installed in your cluster.

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** tab and select **Headlamp**.
3.  Enable **Advanced setup** and adjust the configuration for your needs. For example, you can set up:
    -   the domain where the interface will be available;
    -   ingress settings;
    -   OIDC configuration.
4.  Click **Install**.

To verify that the add-on is installed correctly, run:

```shell
kubectl get pod -n headlamp
```

If the installation was successful, you will see a pod with the `Running` status.

## Authentication

After installation, the Headlamp icon will appear in the cluster dashboard.

![D2492951 3acf 406b 9ac5 04a276e82d10](https://content.hostman.com/assets/05e1c356-6b2c-4304-86ed-6036cd34b5df.png?width=1558&height=866)

Click it to open the interface. If you are not authenticated, you will need to provide a token.

You can obtain the token from the **Dashboard** tab by clicking **Copy** next to **Dashboard token**:

![Dd656c47 9ad0 4ca1 A263 6f7a7f96a915](https://content.hostman.com/assets/76eff32b-5356-4715-8873-12ca992edb71.png?width=1558&height=866)

After authentication, the Headlamp interface will be displayed.

![6454a333 1712 4216 Ad93 808ab30dced1.png](https://content.hostman.com/assets/ab310c7c-d68e-4595-991d-26e5bf0f9fb8.png?width=2926&height=1658)

_[Headlamp](https://headlamp.dev/) interface_

Main sections are:

-   **Cluster**: cluster information and status
-   **Map**: visualization of resources and their relationships
-   **Workloads**: management of workloads (Pods, Deployments, StatefulSets)
-   **Storage**: PVCs, PVs, and storage classes
-   **Network**: services, ingress, and network policies
-   **Gateway**: Gateway API resources
-   **Security**: roles, service accounts, and access policies
-   **Configuration**: ConfigMaps, Secrets, and other settings
-   **Custom Resources**: custom resources (CRDs)
-   **Create**: create resources via the interface

## Configuring Authentication

If the Headlamp interface is exposed externally, it is recommended to configure additional basic authentication.

Headlamp does not support username and password authentication directly. Instead, basic authentication is configured at the `ingress` level.

Create a file with a username and password:

```shell
htpasswd -c auth admin
```

Here, `admin` is the username. You will be prompted to enter the desired password twice.

This command creates a file named `auth`.

If the `htpasswd` utility is not available, install the `apache2-utils` package.

Next, create a secret in the `headlamp` namespace using the generated file:

```shell
kubectl create secret generic headlamp-basic-auth \
  --from-file=auth \
  -n headlamp
```

Go to the **Addons** section in the cluster dashboard and open the installed **Headlamp** add-on.

Enable advanced setup and locate the following block:

```shell
ingress:
 enabled: true
 annotations: {}
```

Remove `{}` next to `annotations` and add the required annotations:

```shell
ingress:
  enabled: true
  annotations:
    nginx.ingress.kubernetes.io/auth-type: basic
    nginx.ingress.kubernetes.io/auth-secret: headlamp-basic-auth
    nginx.ingress.kubernetes.io/auth-realm: "Authentication Required"
```

Click **Save** and wait for the add-on to be updated.

After that, when accessing Headlamp, you will first be prompted for a username and password, and then for a token.

To change the password, create a new `auth` file and update the secret in the cluster.

# NGINX Gateway Fabric

Source: https://hostman.com/docs/kubernetes/addons/nginx-gateway-fabric/

NGINX Gateway Fabric is a Kubernetes Gateway API controller that uses NGINX to handle incoming traffic. You can use it to publish HTTP, HTTPS, gRPC, TCP, and UDP services, configure routing by domain and path, manage TLS, and gradually transition from Ingress to the Gateway API.

Gateway API is the evolution of Ingress. Instead of a single Ingress resource, it splits responsibilities across several dedicated objects:

-   `GatewayClass` defines which controller will manage the gateways.
-   `Gateway` describes the entry point: ports, protocols, domains, and TLS settings.
-   `HTTPRoute` defines HTTP traffic routing rules to backend services.
-   `GRPCRoute`, `TCPRoute`, `UDPRoute`, `TLSRoute` handle other traffic types.

NGINX Gateway Fabric watches Gateway API resources and uses them to create an NGINX data plane: NGINX pods and a service through which external traffic enters the cluster and is routed to Kubernetes services.

## Installation

Before installing NGINX Gateway Fabric from the dashboard, you need to manually install the Gateway API CRDs.

Specify the NGINX Gateway Fabric version in the `ref` parameter. For example, for version `v2.6.3`:

```shell
kubectl kustomize "https://github.com/nginx/nginx-gateway-fabric/config/crd/gateway-api/standard?ref=v2.6.3" | kubectl apply -f -
```

After installing the CRDs:

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** tab and select **NGINX Gateway Fabric**.
3.  (Optional) Enable **Advanced setup** to edit `values.yaml`. For most use cases, the defaults are a good starting point.
4.  Click **Install**.
5.  Wait for the process to complete and verify that the NGINX Gateway Fabric pods are running:

```shell
kubectl get pods -n nginx-gateway
```

All pods should show a `Running` status.

You can also confirm that the Gateway API resources are available in the cluster:

```shell
kubectl api-resources | grep gateway.networking.k8s.io
```

A standard installation of NGINX Gateway Fabric creates a `GatewayClass` named `nginx`. Check its status:

```shell
kubectl get gatewayclass nginx
```

The `ACCEPTED` column should show `True`.

## Usage Example

This example shows how to configure NGINX Gateway Fabric to accept HTTP traffic on a single external IP and route requests to two different services:

-   `http://app.example.com/service1 routes to service1`
-   `http://app.example.com/service2 routes to service2`

Start by creating a dedicated namespace:

```shell
kubectl create namespace nginx-gateway-example
```

### Create a ConfigMap

Create a file called `configmap.yaml` with HTML pages for both services:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
 name: nginx-pages
 namespace: nginx-gateway-example
data:
 service1.html: |
   <html>
     <head><title>Service 1</title></head>
     <body><h1>Service 1</h1></body>
   </html>
 service2.html: |
   <html>
     <head><title>Service 2</title></head>
     <body><h1>Service 2</h1></body>
   </html>
```

Apply the manifest:

```shell
kubectl apply -f configmap.yaml
```

### Create Deployments and Services

Create `service1.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: service1
 namespace: nginx-gateway-example
spec:
 replicas: 2
 selector:
   matchLabels:
     app: service1
 template:
   metadata:
     labels:
       app: service1
   spec:
     containers:
       - name: nginx
         image: nginx:latest
         ports:
           - containerPort: 80
         volumeMounts:
           - name: html
             mountPath: /usr/share/nginx/html
     volumes:
       - name: html
         configMap:
           name: nginx-pages
           items:
             - key: service1.html
               path: index.html
---
apiVersion: v1
kind: Service
metadata:
 name: service1
 namespace: nginx-gateway-example
spec:
 selector:
   app: service1
 ports:
   - name: http
     port: 80
     targetPort: 80
 type: ClusterIP
```

Create `service2.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
 name: service2
 namespace: nginx-gateway-example
spec:
 replicas: 2
 selector:
   matchLabels:
     app: service2
 template:
   metadata:
     labels:
       app: service2
   spec:
     containers:
       - name: nginx
         image: nginx:latest
         ports:
           - containerPort: 80
         volumeMounts:
           - name: html
             mountPath: /usr/share/nginx/html
     volumes:
       - name: html
         configMap:
           name: nginx-pages
           items:
             - key: service2.html
               path: index.html
---
apiVersion: v1
kind: Service
metadata:
 name: service2
 namespace: nginx-gateway-example
spec:
 selector:
   app: service2
 ports:
   - name: http
     port: 80
     targetPort: 80
 type: ClusterIP
```

Apply both manifests:

```shell
kubectl apply -f service1.yaml
kubectl apply -f service2.yaml
```

Verify the pods are running:

```shell
kubectl get pods -n nginx-gateway-example
```

### Create a Gateway

The `Gateway` resource defines the external entry point for your application. With a standard NGINX Gateway Fabric installation, it manages Gateways that use `gatewayClassName: nginx`.

Create `gateway.yaml`:

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
 name: app-gateway
 namespace: nginx-gateway-example
spec:
 gatewayClassName: nginx
 listeners:
   - name: http
     hostname: app.example.com
     protocol: HTTP
     port: 80
     allowedRoutes:
       namespaces:
         from: Same
```

Apply it:

```shell
kubectl apply -f gateway.yaml
```

Once the `Gateway` is created, NGINX Gateway Fabric will deploy an NGINX data plane and a load balancer in the `nginx-gateway-example` namespace. Check the status with:

```shell
kubectl get gateway app-gateway -n nginx-gateway-example
```

Wait until `PROGRAMMED` shows `True` and `ADDRESS` shows an external IP.

You can also inspect the resources that were created:

```shell
kubectl get deployments -n nginx-gateway-example
kubectl get svc -n nginx-gateway-example
```

> [!NOTE]
> NGINX Gateway Fabric creates a dedicated NGINX data plane for each `Gateway`, so you don't need to create a separate `LoadBalancer` service as you would with a classic Ingress controller setup.

### Create an HTTPRoute

`HTTPRoute` defines the routing rules.

Create `httproute.yaml`:

```yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
 name: app-route
 namespace: nginx-gateway-example
spec:
 parentRefs:
   - name: app-gateway
 hostnames:
   - app.example.com
 rules:
   - matches:
       - path:
           type: PathPrefix
           value: /service1
     filters:
       - type: URLRewrite
         urlRewrite:
           path:
             type: ReplacePrefixMatch
             replacePrefixMatch: /
     backendRefs:
       - name: service1
         port: 80
   - matches:
       - path:
           type: PathPrefix
           value: /service2
     filters:
       - type: URLRewrite
         urlRewrite:
           path:
             type: ReplacePrefixMatch
             replacePrefixMatch: /
     backendRefs:
       - name: service2
         port: 80
```

Apply it:

```shell
kubectl apply -f httproute.yaml
```

Confirm the route is accepted:

```shell
kubectl get httproute app-route -n nginx-gateway-example -o yaml
```

The resource status should include both conditions:

```shell
status: "True"
type: Accepted
status: "True"
type: ResolvedRefs
```

This `HTTPRoute` accepts requests for `app.example.com` and routes them to different services based on the path prefix. The `URLRewrite` filter strips the `/service1` and `/service2` prefixes, replacing them with `/`, so NGINX inside each service serves its main page correctly.

### Verify the Setup

Add the load balancer IP as an A record for `app.example.com` in your DNS settings. Once DNS propagates, test both endpoints:

```shell
curl http://app.example.com/service1
curl http://app.example.com/service2
```

If DNS hasn't propagated yet, you can test by IP using the `Host` header:

```shell
curl -H "Host: app.example.com" http://<EXTERNAL_IP>/service1
curl -H "Host: app.example.com" http://<EXTERNAL_IP>/service2
```

Both requests should return the respective Service 1 and Service 2 pages.

### Clean Up

To remove all resources created in this example, run:

```shell
kubectl delete namespace nginx-gateway-example
```

This does not uninstall the NGINX Gateway Fabric add-on. To remove it, go to the **Addons** tab in the cluster dashboard.

## Migrating from Nginx Ingress to NGINX Gateway Fabric

You can run NGINX Gateway Fabric alongside Nginx Ingress and migrate routes gradually. This lets you test Gateway API resources on a separate external IP before switching DNS records or redirecting traffic to the new Gateway.

To automate the conversion of existing Ingress resources, use the [ingress2gateway](https://github.com/kubernetes-sigs/ingress2gateway) utility. It reads Ingress resources from your cluster or from YAML files and outputs equivalent Gateway API resources: `Gateway`, `HTTPRoute`, and related objects.

> [!NOTE]
> **Important**: `ingress2gateway` is a helpful starting point, but it is not a fully automatic migration tool. Some Nginx Ingress annotations may not be supported or may require manual configuration after conversion.

### Prerequisites

Before migrating, make sure your cluster is ready:

-   Nginx Ingress and NGINX Gateway Fabric are both installed.
-   Existing Ingress resources are working correctly through Nginx Ingress.
-   A `GatewayClass` named `nginx` exists in the cluster.

If Nginx Ingress was installed from the Hostman dashboard, it uses an `IngressClass` named `nginx`. You will need this name when running `ingress2gateway`.

Check that both classes are present:

```shell
kubectl get ingressclass
kubectl get gatewayclass
```

The output should include an `IngressClass` named `nginx` and a `GatewayClass` named `nginx`.

### Install ingress2gateway

If you have Go installed locally, run:

```shell
go install github.com/kubernetes-sigs/ingress2gateway@v1.1.0
```

The binary will be placed in `$(go env GOPATH)/bin`. Make sure this directory is in your PATH.

Alternatively, install via Homebrew:

```shell
brew install ingress2gateway
```

Or download a prebuilt binary from the [project releases page](https://github.com/kubernetes-sigs/ingress2gateway/releases).

### Source Setup

In this example, the migration targets an application already published through Nginx Ingress.

The cluster has a namespace called `ingress-migration-demo` containing:

-   An Ingress resource named `migration-source`
-   Services `service1` and `service2`
-   Two routing rules for the domain `app.example.com`:
    -   `/service1` routes to `service1`
    -   `/service2` routes to `service2`

Verify the source Ingress:

```shell
kubectl get ingress -n ingress-migration-demo
```

The `CLASS` column should show `nginx`.

### Convert Ingress Resources

To convert the Ingress to Gateway API resources, run:

```shell
ingress2gateway print \
  --providers=ingress-nginx \
  --ingress-nginx-ingress-class=nginx \
  --namespace=ingress-migration-demo > gateway-migration.yaml
```

The flags in this command:

-   `print` outputs the generated resources to stdout; the `>` redirect saves them to `gateway-migration.yaml`.
-   `--providers=ingress-nginx` specifies the source Ingress controller type.
-   `--ingress-nginx-ingress-class=nginx` filters for Ingress resources using the `nginx` class.
-   `--namespace=ingress-migration-demo` scopes the conversion to the source namespace.

### Review and Fix the Output

Open `gateway-migration.yaml` and review the generated resources before applying them.

Check the `gatewayClassName` field in the `Gateway` resource. For a standard NGINX Gateway Fabric installation, the value should be `nginx`:

```yaml
spec:
  gatewayClassName: nginx
```

Also review the `HTTPRoute` rules. Some Ingress annotations may be converted into filters or match types that need manual adjustment. For example, for standard path prefix routing, use `PathPrefix`:

```yaml
rules:
 - matches:
     - path:
         type: PathPrefix
         value: /service1
   filters:
     - type: URLRewrite
       urlRewrite:
         path:
           type: ReplacePrefixMatch
           replacePrefixMatch: /
   backendRefs:
     - name: service1
       port: 80
```

If the generated file contains `RegularExpression` routes or unsupported annotations, check their compatibility with NGINX Gateway Fabric and replace them with supported Gateway API rules.

### Apply the Gateway API Resources

Once you're satisfied with the output, apply it:

```shell
kubectl apply -f gateway-migration.yaml
```

Verify the `Gateway` has been created and has received an external IP:

```shell
kubectl get gateway -A
```

Check that the `HTTPRoute` has been accepted by the controller:

```shell
kubectl get httproute -A
kubectl describe httproute <route-name> -n <namespace>
```

The `HTTPRoute` status should show both `Accepted=True` and `ResolvedRefs=True`.

### Test Before Switching Traffic

While your DNS records still point to the old Nginx Ingress, verify the new `Gateway` by sending requests directly to its external IP with a `Host` header:

```shell
curl -H "Host: app.example.com" http://<EXTERNAL_IP>/<path>
```

Where:

-   `app.example.com` is the domain from your `HTTPRoute`.
-   `<EXTERNAL_IP>` is the IP address of the new `Gateway`.
-   `<path>` is the path handled by the route.

Compare the responses from the old Ingress and the new `Gateway`. If everything looks correct, update your DNS records to point to the new load balancer's IP.

# NGINX Ingress

Source: https://hostman.com/docs/kubernetes/addons/nginx-ingress/

Ingress is a Kubernetes resource that enables access to services within a cluster via HTTP and HTTPS. It provides routing based on URLs, domains, and other parameters. This article explores the use of Nginx Ingress with three Nginx deployments simulating three different services. We will also configure an SSL certificate to secure the connection.

## Installing Nginx Ingress

First, Nginx Ingress needs to be installed in the cluster.

1.  Go to the **Kuberenetes** section and click on the cluster.
2.  In the **Addons** tab, click on the three dots next to **Nginx Ingress**.
3.  Select **Install**.

After installation, verify that Ingress is functioning correctly by running the command:

```shell
kubectl get pods -n ingress-nginx
```

Ensure that all pods have the `Running` status.

## Configuring Deployments and Services

Let’s consider an example of using NGINX Ingress. We will deploy three `Deployments` based on Nginx images, each simulating a separate service. For each `Deployment`, we will create a `Service` of type `ClusterIP`—the default service type in Kubernetes—which provides an internal IP address within the cluster. This type of service is not directly accessible from outside the cluster; however, it can be exposed to external traffic using an Ingress.

For convenience, we will create a separate namespace that will contain all the manifests:

```shell
kubectl create namespace ingress-example
```

To distinguish the services from each other, we will create a `ConfigMap` containing three different HTML pages. Create a file named `configmap.yaml` with the following content:

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: service-config
  namespace: ingress-example
data:
  service1.html: |
    <html>
      <head><title>Service 1</title></head>
      <body><h1>Welcome to Service 1!</h1></body>
    </html>
  service2.html: |
    <html>
      <head><title>Service 2</title></head>
      <body><h1>Welcome to Service 2!</h1></body>
    </html>
  service3.html: |
    <html>
      <head><title>Service 3</title></head>
      <body><h1>Welcome to Service 3!</h1></body>
    </html>
```

Next, we will define the `Deployments`.

**service1-deployment.yaml**:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service1
  namespace: ingress-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service1
  template:
    metadata:
      labels:
        app: service1
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /usr/share/nginx/html
      volumes:
      - name: config-volume
        configMap:
          name: service-config
          items:
          - key: service1.html
            path: index.html
---
apiVersion: v1
kind: Service
metadata:
  name: service1
  namespace: ingress-example
spec:
  selector:
    app: service1
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80
  type: ClusterIP
```

Manifest explanation:

-   `Deployment`
    -   `replicas`: `2` specifies that two replicas of Nginx pods will be running.
    -   The `selector` and `template.metadata.labels` section defines how the service will locate the pods.
    -   `volumeMounts` and `volumes` are used to mount the `service1.html` file from a `ConfigMap` into the directory from which Nginx serves content by default.
-   `Service`
    -   `ClusterIP` means the service will be accessible only within the cluster via an assigned IP address. For external access, we will use Ingress.

The manifests for `service2` and `service3` are similar, differing only in the service name and the HTML file used.

**service2-deployment.yaml**:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service2
  namespace: ingress-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service2
  template:
    metadata:
      labels:
        app: service2
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /usr/share/nginx/html
      volumes:
      - name: config-volume
        configMap:
          name: service-config
          items:
          - key: service2.html
            path: index.html
---
apiVersion: v1
kind: Service
metadata:
  name: service2
  namespace: ingress-example
spec:
  selector:
    app: service2
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80
  type: ClusterIP
```

**service3-deployment.yaml**:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service3
  namespace: ingress-example
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service3
  template:
    metadata:
      labels:
        app: service3
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80
        volumeMounts:
        - name: config-volume
          mountPath: /usr/share/nginx/html
      volumes:
      - name: config-volume
        configMap:
          name: service-config
          items:
          - key: service3.html
            path: index.html
---
apiVersion: v1
kind: Service
metadata:
  name: service3
  namespace: ingress-example
spec:
  selector:
    app: service3
  ports:
  - protocol: TCP
    port: 80
    targetPort: 80
  type: ClusterIP
```

Apply the maniests:

```shell
kubectl apply -f configmap.yaml
kubectl apply -f service1-deployment.yaml
kubectl apply -f service2-deployment.yaml
kubectl apply -f service3-deployment.yaml
```

Check the pods statuses:

```shell
kubectl get pods -n ingress-example
```

All pods should have the `Running` status. 

## Creating Ingress

With Ingress, we will define which traffic (based on domains and paths) should be redirected to the corresponding services. We will create the `ingress.yaml` manifest.

```yml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: ingress-example
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
  - host: ingress1.example.com
    http:
      paths:
      - path: /service1
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 80
      - path: /service2
        pathType: Prefix
        backend:
          service:
            name: service2
            port:
              number: 80
  - host: ingress2.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: service3
            port:
              number: 80
```

Manifest explanation:

-   `rules.host` specifies the domain to which Ingress will be bound.
-   `paths` defines the routing rules:  
    -   Requests to `ingress1.example.com/service1` will be redirected to `service1`.
    -   Requests to `ingress1.example.com/service2` will be redirected to `service2`.
    -   Requests to `ingress2.example.com/` will be redirected to `service3`.

Apply the manifest:

```shell
kubectl apply -f ingress.yaml
```

## Creating a LoadBalancer

To access Nginx Ingress from an external network, we will create a `Service` of type `LoadBalancer`, which will handle load balancing and provide an external IP address. We will prepare the `loadbalancer.yaml` manifest for this.

```yml
apiVersion: v1
kind: Service
metadata:
  name: ingress-nginx
  namespace: ingress-nginx
spec:
  selector:
    app.kubernetes.io/name: ingress-nginx
  ports:
    - name: http
      port: 80
      targetPort: 80
    - name: https
      port: 443
      targetPort: 443
  type: LoadBalancer
```

Apply the manifest:

```shell
kubectl apply -f loadbalancer.yaml
```

Wait until the load balancer is created and verify that it has an external IP address:

```shell
kubectl get services -n ingress-nginx
```

The external IP will be displayed in the `EXTERNAL-IP` column.

Add the external IP to the domain’s DNS settings as A records for the domains `ingress1.example.com` and `ingress2.example.com`. Once the DNS updates, your domains will point to this load balancer, and you will be able to access the services via external URLs:

-   `http://ingress1.example.com/service1` — will display the header "Welcome to Service 1!".
-   `http://ingress1.example.com/service2` — will display the header "Welcome to Service 2!".
-   `http://ingress2.example.com/` — will display the header "Welcome to Service 3!".

## Configuring an SSL Certificate

To ensure a secure connection in Nginx Ingress, you need to add an existing SSL certificate as a Kubernetes Secret and specify this secret in the Ingress manifest.

If you want to automate certificate issuance and renewal (e.g., using Let’s Encrypt), use cert-manager.

### Preparing Certificate and Key Files

Save the `tls.key` (private key) and `tls.crt` (certificate) files locally. Ensure that the certificate is not expired and matches the domains you want to secure.

### Creating a Kubernetes Secret

To add the certificate to the cluster, encode the files in Base64 and create a `Secret` manifest. Run the following commands in the terminal:

```shell
base64 -w 0 ./tls.crt
base64 -w 0 ./tls.key
```

Then, create the `tls-secret.yaml` file with the following content:

```yml
apiVersion: v1
kind: Secret
metadata:
  name: ingress-example-tls
  namespace: ingress-example
type: kubernetes.io/tls
data:
  tls.crt: |-
    <BASE64_ENCODED_CERTIFICATE>
  tls.key: |-
    <BASE64_ENCODED_KEY>
```

Save the file and apply the manifest:

```shell
kubectl apply -f tls-secret.yaml
```

Verify that the key and certificate values are not empty by running:

```shell
kubectl describe secret ingress-example-tls -n ingress-example
```

### Updating the Ingress Manifest

Update your `ingress.yaml` manifest by adding the `tls` section and specifying the created secret.

```yml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example-ingress
  namespace: ingress-example
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  tls:
  - hosts:
    - ingress1.example.com
    - ingress2.example.com
    secretName: ingress-example-tls
  rules:
  - host: ingress1.example.com
    http:
      paths:
      - path: /service1
        pathType: Prefix
        backend:
          service:
            name: service1
            port:
              number: 80
      - path: /service2
        pathType: Prefix
        backend:
          service:
            name: service2
            port:
              number: 80
  - host: ingress2.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: service3
            port:
              number: 80
```

Apply the updated manifest:

```shell
kubectl apply -f ingress.yaml
```

Now, when accessing `ingress1.example.com` or `ingress2.example.com` over HTTPS, the browser will use the certificate stored in the `ingress-example-tls` secret. This ensures that traffic to your services is secured.

If you have multiple certificates for different domains, create a `Secret` for each of them. For example, for `example.com` and `example.org`, create two separate secrets.

Then, update the Ingress manifest by adding a `tls` section for each domain.

```yml
spec:
  tls:
  - hosts:
    - example.com
    secretName: example-com-tls
  - hosts:
    - example.org
    secretName: example-org-tls
```

Each domain will then use its respective certificate as specified in the corresponding secret.

# OpenFaaS

Source: https://hostman.com/docs/kubernetes/addons/openfaas/

OpenFaaS is an open-source platform for running functions (FaaS) on top of Kubernetes. It simplifies the deployment of small code units that execute on demand or in response to events.

At its core, OpenFaaS follows the Function as a Service (FaaS) model: you write a function, package it into a Docker image, and OpenFaaS handles scaling, networking, and lifecycle management.

It offers a user-friendly web interface and a command-line tool called `faas-cli`. You can write functions in popular languages such as Python, Node.js, Go, and others using pre-built templates.

The complete documentation for OpenFaaS on Kubernetes is available on the [official website](https://docs.openfaas.com/).

## Installing the Addon

To install OpenFaaS:

1.  Go to the **Kubernetes** section and click on your cluster.
2.  In the **Addons** tab, click **OpenFaaS**.
3.  In the **Configuration** window, find the `ingress` section and enable it by setting `enabled: true`. Also, specify your domain in the `host` parameter. This will simplify access to the dashboard and allow usage of `faas-cli`. If you enable `ingress`, you can disable `exposeServices`, which is used by default.
4.  Once parameters are set, click **Install** and wait for the installation to finish.

To verify everything is running, check the status of pods in the `openfaas-fn` namespace:

```shell
kubectl get pods -n openfaas-fn
```

Example output:

```shell
NAME                            READY   STATUS    RESTARTS      AGE
alertmanager-57767d864c-hdqdn   1/1     Running   0             19h
gateway-5f9c4b5754-ksr6x        2/2     Running   1 (19h ago)   19h
nats-6ddf479847-dxr2g           1/1     Running   0             19h
prometheus-6cbd946f66-wqdf8     1/1     Running   0             19h
queue-worker-57c7479989-bw282   1/1     Running   0             19h
```

If all pods are in `Running` status, the installation was successful.

## Installing the CLI

To work with OpenFaaS from the terminal, you need the `faas-cli` tool. It allows you to create functions, build and push images, deploy them to the cluster, invoke functions, and check their status.

It is available for Linux, macOS, and Windows. Use the following commands to install it:

**Linux/macOS**

```shell
curl -sSL https://cli.openfaas.com | sh
```

**macOS**

```shell
curl -sSL https://cli.openfaas.com | sh
```

Or, via Homebrew:

```shell
brew install faas-cli
```

**Windows (PowerShell)**

```shell
$version = (Invoke-WebRequest "https://api.github.com/repos/openfaas/faas-cli/releases/latest" | ConvertFrom-Json)[0].tag_name

(New-Object System.Net.WebClient).DownloadFile("https://github.com/openfaas/faas-cli/releases/download/$version/faas-cli.exe", "faas-cli.exe")
```

Verify the installation:

```shell
faas-cli version
```

## Example Usage

In this example, we will:

-   Deploy the OpenFaaS addon.
-   Bind a domain for easy dashboard access and CLI use.
-   Deploy a function from the built-in store.
-   Create and deploy a custom function using Docker Hub.

Requirements:

-   A domain or subdomain for OpenFaaS access.
-   Installed Nginx Ingress addon.
-   A Docker Hub account (for custom functions).
-   Installed `faas-cli` and Docker.

#### Deploying the Addon

Go to the dashboard and install the **OpenFaaS** addon. In the **Configuration** section, enable `ingress` by setting `enabled: true` and specifying your domain in the `host` field. Then start the installation.

#### Creating a Load Balancer

Create a `loadbalancer.yaml` manifest:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: ingress-nginx-lb
  namespace: ingress-nginx
spec:
  selector:
    app.kubernetes.io/name: ingress-nginx
  type: LoadBalancer
  ports:
    - name: http
      port: 80
      targetPort: 80
      appProtocol: k8s.hostman.com/proto-http
    - name: https
      port: 443
      targetPort: 443
      appProtocol: k8s.hostman.com/proto-https
```

Apply it:

```shell
kubectl apply -f loadbalancer.yaml
```

Set the balancer’s IP as the A record of your domain. If you're using Hostman NS servers, just select the newly created load balancer. Otherwise, get its IP manually:

```shell
kubectl get svc --all-namespaces --field-selector spec.type=LoadBalancer
```

The IP will be under the `EXTERNAL-IP` column.

Visit the domain you configured—a basic auth prompt will appear.

Use the login `admin` and retrieve the password using:

```shell
kubectl -n openfaas-fn get secret basic-auth -o jsonpath="{.data.basic-auth-password}" | base64 --decode
```

After logging in, the dashboard will open.

![E036c968 493b 4791 Ab5a C7966782647e.png](https://content.hostman.com/assets/8dbdb2f7-c1d7-4088-96d2-97ec77ec8b08.png?width=2894&height=848)

_[OpenFaaS](https://www.openfaas.com/) Dashboard_

#### Working with Functions

Let’s move on to using functions. We’ll install a function from the built-in OpenFaaS store.

First, log in via the CLI. This will allow you to run commands related to function management:

```shell
faas-cli login \
  --gateway http://<domain> \
  --username admin \
  --password <password>
```

Where:

-   `domain` — the address specified during OpenFaaS installation;
-   `admin` — the default username;
-   `password` — the password can be retrieved with the following command:

```shell
kubectl -n openfaas-fn get secret basic-auth -o jsonpath="{.data.basic-auth-password}" | base64 --decode
```

Now install the `figlet` function, which converts text into ASCII art:

```shell
faas-cli store deploy figlet \
  --gateway http://<domain>
```

Make sure the function has been installed:

```shell
faas-cli list \
  --gateway http://<domain>
```

The list will now contain the `figlet` function with a status of `Ready`.

Invoke the function and pass a string as input:

```shell
echo "Hostman" | faas-cli invoke figlet \
  --gateway http://<domain>
```

You’ll receive ASCII art with the given text in response.

Now let’s go over deploying a custom function. Choose a template:

```shell
faas-cli template store list
```

Create a new function based on the desired template—for example, `python3-http`:

```shell
faas-cli new hello-k8s --lang python3-http
```

The following will be created:

-   `hello-k8s/handler.py` — the function code;
-   `stack.yaml` — the function manifest.

Before building, edit the `stack.yaml` file and specify the path to your Docker Hub image. For example:

```yaml
functions:
  hello-k8s:
    lang: python3-http
    handler: ./hello-k8s
    image: dockerhubuser/hello-k8s:latest
```

In the image `field`, specify your Docker Hub username and the image name. Note that OpenFaaS Community Edition only supports public images.

Build the image:

```shell
faas-cli build -f stack.yaml
```

After the image is built, push it to Docker Hub:

```shell
faas-cli push -f stack.yaml
```

Finally, deploy the function to your cluster:

```shell
faas-cli deploy -f stack.yaml \
  --gateway http://<domain>
```

After running the command, you’ll get a link to access the function.

![67ed7fe8 9a22 4515 Aeb8 0e9f49c8a07e.png](https://content.hostman.com/assets/0854d11f-63bb-4a4f-b3c4-c848c42e4406.png?width=1550&height=282)

Open the link. You should see the message "Hello from OpenFaaS!".

# Traefik

Source: https://hostman.com/docs/kubernetes/addons/traefik/

Traefik is an ingress controller and reverse proxy for cloud environments and Kubernetes. It automatically discovers services, provides SSL/TLS termination, and offers advanced routing capabilities. Using Traefik in Kubernetes allows flexible traffic routing to services within the cluster.

## Installation

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** tab and select **Traefik**.
3.  The installation wizard will open. You can upload your own `values.yaml` file for customization or keep the default settings. Start the installation by clicking the **Install** button. 
4.  Wait for the installation to complete. After that, make sure all pods in the **traefik** namespace are running and have the `Running` status:

```shell
kubectl get pods -n traefik
```

## Usage

By default, the installed Traefik configuration uses four entry points:

-   :8000/tcp — HTTP (`web`)
-   :8443/tcp — HTTPS (`websecure`)
-   :8080/tcp — API Dashboard (`traefik`)
-   :9100/tcp — Prometheus Metrics (`metrics`)

To work with Traefik, you need to create a `Service` that will route traffic to your application: 

```yml
apiVersion: v1
kind: Service
metadata:
  name: example-service
  namespace: default
spec:
  selector:
    app: example-app
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
```

This manifest creates the `example-service` in the `default` namespace, which:

-   Routes HTTP traffic (port 80).
-   Directs it to pods with the label `app: example-app`.
-   Forwards requests to `targetPort: 80` within the pods.

Now, you can configure routing through Traefik using `IngressRoute`:

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: example-service-route
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`service.example.com`)
      kind: Rule
      services:
        - name: example-service
          port: 80
```

In this manifest:

-   `entryPoints: web` — specifies that routing occurs via HTTP (8000/tcp).
-   `match: Host('service.example.com')` — defines the routing rule based on the domain name.
-   Requests are directed to the `example-service` on port 80.

## Example Usage

Let's explore an example using Traefik. We will create two Nginx deployments that will work on two different domains — `service1.example.com` and `service2.example.com`. We will also configure a load balancer and routing through Traefik. Finally, we will configure SSL certificates using Traefik.

### Creating a ConfigMap

First, create the `configmap-nginx.yaml` file, which defines HTML pages for each service:

```yml
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-pages
  namespace: default
data:
  index1.html: |
    <!DOCTYPE html>
    <html>
    <head><title>Service 1</title></head>
    <body><h1>Service 1</h1></body>
    </html>
  index2.html: |
    <!DOCTYPE html>
    <html>
    <head><title>Service 2</title></head>
    <body><h1>Service 2</h1></body>
    </html>
```

### Creating Deployments for Nginx

The `service1-nginx.yaml` manifest describes the deployment for the first service:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service1
  namespace: default
  labels:
    app: service1
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service1
  template:
    metadata:
      labels:
        app: service1
    spec:
      containers:
        - name: nginx
          image: nginx
          volumeMounts:
            - name: html-volume
              mountPath: /usr/share/nginx/html
          ports:
            - containerPort: 80
      volumes:
        - name: html-volume
          configMap:
            name: nginx-pages
            items:
              - key: index1.html
                path: index.html
```

The `service2-nginx.yaml` manifest describes the deployment for the second service:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: service2
  namespace: default
  labels:
    app: service2
spec:
  replicas: 2
  selector:
    matchLabels:
      app: service2
  template:
    metadata:
      labels:
        app: service2
    spec:
      containers:
        - name: nginx
          image: nginx
          volumeMounts:
            - name: html-volume
              mountPath: /usr/share/nginx/html
          ports:
            - containerPort: 80
      volumes:
        - name: html-volume
          configMap:
            name: nginx-pages
            items:
              - key: index2.html
                path: index.html
```

### Creating Services

Define the services that Traefik will route traffic to. 

The `service1-service.yaml` manifest: 

```yml
apiVersion: v1
kind: Service
metadata:
  name: service1
  namespace: default
spec:
  selector:
    app: service1
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
```

This manifest creates the `service1` service, which accepts HTTP requests on port 80 and redirects them to pods labeled `app: service1`. 

The `service2-service.yaml` manifest:

```yml
apiVersion: v1
kind: Service
metadata:
  name: service2
  namespace: default
spec:
  selector:
    app: service2
  ports:
    - protocol: TCP
      port: 80
      targetPort: 80
```

### Creating Routes in Traefik

The `service1-ingressroute.yaml` manifest describes the route for the first service:

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: service1-route
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`service1.example.com`)
      kind: Rule
      services:
        - name: service1
          port: 80
```

This manifest defines an `IngressRoute` for `service1.example.com`. Let's break down its components:

-   `entryPoints: web` — the route is available via HTTP (port 80, specified in the Traefik load balancer).
-   `match: Host('service1.example.com')` — this route is triggered when accessing `service1.example.com`.
-   `name: service1` — the route forwards traffic to the `service1` service.
-   `port: 80` — traffic is sent to port 80 inside the `service1` Kubernetes service.

The `service2-ingressroute.yaml` manifest describes the route for the second service:

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: service2-route
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`service2.example.com`)
      kind: Rule
      services:
        - name: service2
          port: 80
```

### Configuring the Load Balancer

Define the load balancer for Traefik in `traefik-loadbalancer.yaml`:

```yml
apiVersion: v1
kind: Service
metadata:
  name: traefik
  namespace: traefik
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: traefik
  ports:
    - name: web
      port: 80
      targetPort: 8000
    - name: websecure
      port: 443
      targetPort: 8443
```

### Applying the Configuration

Apply all manifests:

```shell
kubectl apply -f ./
```

After creating the load balancer, set its IP address as the A records for the domains. Now, the services are accessible at:

-   `http://service1.example.com`
-   `http://service2.example.com`

We have configured two services in Kubernetes using Traefik, ensuring routing and load balancing.

## Configuring SSL

Traefik allows obtaining SSL certificates in two ways:

-   Using built-in Traefik features.
-   Using [cert-manager](https://hostman.com/docs/kubernetes/addons/cert-manager/).

The choice depends on the cluster configuration. If other Ingress controllers are used, `cert-manager` is recommended for centralized certificate management. If only Traefik is used in the cluster, you can utilize its built-in certificate retrieval feature.

### Updating Traefik Configuration

To enable Let's Encrypt support, modify the Traefik configuration:

1.  Go to the cluster management panel → **Addons** → select **Traefik**.
2.  Enable the **Advanced setup** mode.
3.  Adjust the configuration:

```yml
image:
  registry: docker.io

deployment:
  kind: Deployment

updateStrategy:
  rollingUpdate:
    maxUnavailable: 1
    maxSurge: 0

additionalArguments:
  - "--certificatesresolvers.le.acme.email=admin@example.com"
  - "--certificatesresolvers.le.acme.storage=/data/acme.json"
  - "--certificatesresolvers.le.acme.tlschallenge=true"
```

Changes made:

-   -   By default, Traefik is installed as a `DaemonSet`. In this mode, it cannot obtain certificates using Traefik. Therefore, the deployment type is changed to `Deployment`.
    -   Added the `additionalArguments` segment. Set your email for Let's Encrypt registration in `--certificatesresolvers.le.acme.email`.

4.  Save the changes and wait for the update to complete.

### Verifying Configuration

After updating, ensure the configuration is correctly applied:

```shell
kubectl get pod -n traefik
```

Then, check for ACME parameters:

```shell
kubectl get pod <pod_name> -n traefik -o yaml | grep acme
```

The output should contain lines like:

```shell
 - --certificatesresolvers.le.acme.email=admin@example.com
  - --certificatesresolvers.le.acme.storage=/data/acme.json
  - --certificatesresolvers.le.acme.tlschallenge=true
```

### Automatic Redirect from HTTP to HTTPS

Create a middleware for automatic redirection from HTTP to HTTPS.

**redirect-https.yaml**: 

```yml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: redirect-to-https
  namespace: default
spec:
  redirectScheme:
    scheme: https
    permanent: true
```

Apply the manifest:

```shell
kubectl apply -f redirect-https.yaml
```

### Updating IngressRoute

Update `IngressRoute` to add middleware for redirecting HTTP to HTTPS.

The `service1-ingressroute.yaml` manifest:

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: service1-route
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`service1.example.com`)
      kind: Rule
      middlewares:
        - name: redirect-to-https
      services:
        - name: service1
          port: 80
```

The `service2-ingressroute.yaml` manifest:

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: service2-route
  namespace: default
spec:
  entryPoints:
    - web
  routes:
    - match: Host(`service2.example.com`)
      kind: Rule
      middlewares:
        - name: redirect-to-https
      services:
        - name: service2
          port: 80
```

We have added the middleware `redirect-to-https` to the routing manifests `service1-ingressroute.yaml`, which automatically redirects HTTP requests to HTTPS.

Update the manifests:

```shell
kubectl apply -f service1-ingressroute.yaml
kubectl apply -f service2-ingressroute.yaml
```

### Configuring HTTPS IngressRoute

Now we need to create separate `IngressRoute` resources for HTTPS since standard HTTP routes do not handle TLS. For HTTPS to work, we need to specify a `certResolver`, which will use Let's Encrypt to automatically obtain certificates.

In the new `IngressRoute`, we specify the `entryPoints: websecure` and the `tls` parameter, which enables encryption support.

The `service1-ingressroute-https.yaml` manifest:

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: service1-route-https
  namespace: default
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`service1.example.com`)
      kind: Rule
      services:
        - name: service1
          port: 80
  tls:
    certResolver: le
```

The `service2-ingressroute-https.yaml` manifest:

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: service2-route-https
  namespace: default
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`service2.example.com`)
      kind: Rule
      services:
        - name: service2
          port: 80
  tls:
    certResolver: le
```

Apply the manifests for the new routes:

```shell
kubectl apply -f service1-ingressroute-https.yaml
kubectl apply -f service2-ingressroute-https.yaml
```

### Checking Certificate Issuance

Verify certificate issuance with:

```shell
kubectl logs -n traefik -l app.kubernetes.io/name=traefik | grep acme
```

Now, services are accessible via HTTPS:

-   `https://service1.example.com`
-   `https://service2.example.com`

We have configured automatic SSL certificate issuance with Let's Encrypt in Traefik, ensuring secure connections to services.

## Configuring the Dashboard

Traefik provides a web interface that allows you to monitor the status of routes, services, middleware, and other resources managed by the Traefik instance. The dashboard helps diagnose issues, analyze traffic routing, and manage configuration.

By default, the Traefik dashboard is accessible without authentication, which poses a security risk since any user can view information about running services. To secure access, we will configure basic authentication using `middleware`.

1.  Generate a password hash:
    

```shell
mkpasswd -m bcrypt "password"
```

2.  Encode the credentials in base64:
    

```shell
echo -n 'username:generated_hash' | base64
```

3.  Define a secret in `dashboard-secret.yaml`:
    

```yml
apiVersion: v1
kind: Secret
metadata:
  name: dashboard-auth-secret
  namespace: traefik
type: Opaque
data:
  users: |
    login:base64_encoded_password
```

4.  Apply the manifest:
    

```shell
kubectl apply -f dashboard-secret.yaml
```

5.  Define middleware in `dashboard-auth.yaml`:
    

```yml
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: dashboard-auth
  namespace: traefik
spec:
  basicAuth:
    secret: dashboard-auth-secret
```

6.  Apply the manifest:
    

```shell
kubectl apply -f dashboard-auth.yaml
```

7.  Finally, define `IngressRoute` for the dashboard in `dashboard-ingress.yaml`:
    

```yml
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: traefik-dashboard
  namespace: traefik
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`dashboard.example.com`)
      kind: Rule
      middlewares:
        - name: dashboard-auth
      services:
        - kind: TraefikService
          name: api@internal
  tls:
    certResolver: le
```

This manifest defines a route for accessing the Traefik dashboard via HTTPS, applying basic authentication.

Parameters description:

-   -   `entryPoints: websecure` — specifies that the route will only be accessible via HTTPS.
    -   `match: Host(dashboard.example.com)` — directs requests received for `dashboard.example.com` to the dashboard.
    -   `middlewares` — applies the previously created `dashboard-auth` middleware, which enables basic HTTP authentication.
    -   `services` — directs requests to the built-in `api@internal` service, responsible for displaying the dashboard.
    -   `tls.certResolver: le` — enables automatic SSL certificate issuance via Let's Encrypt.

8.  Apply the manifest:
    

```shell
kubectl apply -f dashboard-ingress.yaml
```

9.  Now, visit `https://dashboard.example.com`. After authentication, you will see the Traefik dashboard.

# Vault

Source: https://hostman.com/docs/kubernetes/addons/vault/

Vault is a secrets management system by HashiCorp that allows you to securely store and access tokens, passwords, certificates, and other sensitive data.

In Kubernetes, Vault is used as an external secrets storage and can provide centralized access management.

### Installation

You can install Vault into the cluster through the Hostman dashboard. To do this:

1.  Go to the **Kubernetes** section and click on your cluster.
    
2.  In the **Addons** tab, click **Vault**.
    
3.  In the **Configuration** window, you can modify the installation parameters:
    

-   Switch to advanced installation mode;
    
-   Edit the configuration manually or upload your own `values.yaml` file;
    

5.  Once parameters are set, click **Install** and wait for the installation to finish.
    

The default configuration assumes that the add-on will run in **dev mode**. This is a simplified mode in which Vault automatically initializes itself, requires no storage configuration, and uses a preconfigured `root token`. The dev mode is suitable only for testing and development; **it is not secure for production**.

### Verifying the Installation

After the installation is complete, make sure that the Vault components have started successfully. Run the following command:

```shell
kubectl get pods -n vault
```

You should see a list of pods, including:

-   `vault-0`: the main Vault pod;
    
-   `vault-agent-injector-xxx`: the service responsible for automatically injecting secrets into pods;
    
-   Additional pods (for example, `vault-1`, `vault-2`) if Vault is installed in HA mode.
    

If the configuration includes the option `ui = true` (enabled by default), you can access the Vault web interface.

1.  Forward the port using the following command:
    

```shell
kubectl port-forward -n vault svc/vault 8200:8200
```

2.  Open a browser and go to:
    

```shell
http://localhost:8200
```

In dev mode, Vault is already initialized, and you can log in using the token specified in the configuration. By default, the value is:

```shell
devRootToken: "root"
```

![Cfcd1d4a 6972 4dd6 A46f 8a12771aee34.png](https://content.hostman.com/assets/649edef5-5225-49db-99ac-cb644fe7e318.png?width=1612&height=875)

_[HashiCorp Vault](https://www.hashicorp.com/en/products/vault) Dashboard_

### HA Mode

HA (High Availability) mode allows you to deploy multiple Vault instances with distributed data storage. This provides:

-   Fault tolerance: if one instance fails, the cluster continues to operate
-   Centralized storage
-   Scalability

One of the pods becomes the leader, while the others run in standby mode. Read/write requests are handled only by the leader, but if it becomes unavailable, control automatically passes to one of the standby pods.

> [!NOTE]
> For this mode to work, we recommend installing the CSI-S3 add-on.

To enable HA mode, specify the following parameters in the add-on configuration:

```shell
server.dev.enabled: false          # disable dev mode  
server.standalone.enabled: false   # disable standalone mode  
server.ha.enabled: true            # enable HA mode  
server.ha.replicas: 3              # specify number of replicas  
server.ha.raft.enabled: true       # use built-in Raft storage  
server.dataStorage.storageClass: csi-s3   # connect S3 storage via CSI
```

Example configuration (click to expand)

```yaml
global:
  enabled: true
  namespace: ""
  imagePullSecrets: []
  tlsDisable: true
  externalVaultAddr: ""
  openshift: false
  psp:
    enable: false
    annotations: |
      seccomp.security.alpha.kubernetes.io/allowedProfileNames: docker/default,runtime/default
      apparmor.security.beta.kubernetes.io/allowedProfileNames: runtime/default
      seccomp.security.alpha.kubernetes.io/defaultProfileName:  runtime/default
      apparmor.security.beta.kubernetes.io/defaultProfileName:  runtime/default
  serverTelemetry:
    prometheusOperator: false

injector:
  enabled: true
  replicas: 1
  port: 8080
  leaderElector:
    enabled: true
  metrics:
    enabled: false
  externalVaultAddr: ""

  image:
    repository: "hashicorp/vault-k8s"
    tag: "1.7.0"
    pullPolicy: IfNotPresent

  agentImage:
    repository: "hashicorp/vault"
    tag: "1.20.4"

  agentDefaults:
    cpuLimit: "500m"
    cpuRequest: "250m"
    memLimit: "128Mi"
    memRequest: "64Mi"
    template: "map"
    templateConfig:
      exitOnRetryFailure: true
      staticSecretRenderInterval: ""

  livenessProbe:
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 2
    successThreshold: 1
    timeoutSeconds: 5

  readinessProbe:
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 2
    successThreshold: 1
    timeoutSeconds: 5

  startupProbe:
    failureThreshold: 12
    initialDelaySeconds: 5
    periodSeconds: 5
    successThreshold: 1
    timeoutSeconds: 5

  authPath: "auth/kubernetes"
  logLevel: "info"
  logFormat: "standard"
  revokeOnShutdown: false

  webhook:
    failurePolicy: Ignore
    matchPolicy: Exact
    timeoutSeconds: 30
    namespaceSelector: {}
    objectSelector: |
      matchExpressions:
      - key: app.kubernetes.io/name
        operator: NotIn
        values:
        - {{ template "vault.name" . }}-agent-injector

    annotations: {}
  failurePolicy: Ignore
  namespaceSelector: {}
  objectSelector: {}
  webhookAnnotations: {}

  certs:
    secretName: null
    caBundle: ""
    certName: tls.crt
    keyName: tls.key
  securityContext:
    pod: {}
    container: {}
  resources: {}
  extraEnvironmentVars: {}
  affinity: |
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchLabels:
              app.kubernetes.io/name: {{ template "vault.name" . }}-agent-injector
              app.kubernetes.io/instance: "{{ .Release.Name }}"
              component: webhook
          topologyKey: kubernetes.io/hostname
  topologySpreadConstraints: []
  tolerations: []
  nodeSelector: {}
  priorityClassName: ""
  annotations: {}
  extraLabels: {}
  hostNetwork: false
  service:
    annotations: {}
  serviceAccount:
    annotations: {}
  podDisruptionBudget: {}
  strategy: {}

server:
  enabled: true
  enterpriseLicense:
    secretName: ""
    secretKey: "license"

  image:
    repository: "hashicorp/vault"
    tag: "1.20.4"
    pullPolicy: IfNotPresent

  updateStrategyType: "OnDelete"

  logLevel: "info"
  logFormat: "standard"

  resources: {}

  ingress:
    enabled: false
    labels: {}
    annotations: {}
    ingressClassName: ""
    pathType: Prefix
    activeService: true
    hosts:
      - host: chart-example.local
        paths: []
    extraPaths: []
    tls: []

  hostAliases: []

  route:
    enabled: false
    activeService: true
    labels: {}
    annotations: {}
    host: chart-example.local
    tls:
      termination: passthrough

  authDelegator:
    enabled: true

  extraInitContainers: null

  extraContainers: null

  shareProcessNamespace: false

  extraArgs: ""

  extraPorts: null

  readinessProbe:
    enabled: true
    port: 8200
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 5
    successThreshold: 1
    timeoutSeconds: 3

  livenessProbe:
    enabled: false
    execCommand: []
    path: "/v1/sys/health?standbyok=true"
    port: 8200
    failureThreshold: 2
    initialDelaySeconds: 60
    periodSeconds: 5
    successThreshold: 1
    timeoutSeconds: 3

  terminationGracePeriodSeconds: 10

  preStopSleepSeconds: 5

  preStop: []

  postStart: []

  extraEnvironmentVars: {}

  extraSecretEnvironmentVars: []

  extraVolumes: []

  volumes: null

  volumeMounts: null

  affinity: |
    podAntiAffinity:
      requiredDuringSchedulingIgnoredDuringExecution:
        - labelSelector:
            matchLabels:
              app.kubernetes.io/name: {{ template "vault.name" . }}
              app.kubernetes.io/instance: "{{ .Release.Name }}"
              component: server
          topologyKey: kubernetes.io/hostname

  topologySpreadConstraints: []

  tolerations: []

  nodeSelector: {}

  networkPolicy:
    enabled: false
    egress: []

    ingress:
      - from:
        - namespaceSelector: {}
        ports:
        - port: 8200
          protocol: TCP
        - port: 8201
          protocol: TCP

  priorityClassName: ""

  extraLabels: {}

  annotations: {}

  includeConfigAnnotation: false

  service:
    enabled: true
    active:
      enabled: true
      annotations: {}
    standby:
      enabled: true
      annotations: {}
    instanceSelector:
      enabled: true
    ipFamilyPolicy: ""
    ipFamilies: []
    publishNotReadyAddresses: true
    externalTrafficPolicy: Cluster
    port: 8200
    targetPort: 8200
    annotations: {}

  dataStorage:
    enabled: true
    size: 1Gi
    mountPath: "/vault/data"
    storageClass: "csi-s3"
    accessMode: ReadWriteOnce
    annotations: {}
    labels: {}

  persistentVolumeClaimRetentionPolicy: {}

  auditStorage:
    enabled: false
    size: 1Gi
    mountPath: "/vault/audit"
    storageClass: "csi-s3"
    accessMode: ReadWriteOnce
    annotations: {}
    labels: {}

  dev:
    enabled: false
    devRootToken: "root"

  standalone:
    enabled: false
    config: |-
      ui = true
      listener "tcp" {
        tls_disable = 1
        address = "[::]:8200"
        cluster_address = "[::]:8201"
      }
      storage "file" {
        path = "/vault/data"
      }

  ha:
    enabled: true
    replicas: 3
    apiAddr: null
    clusterAddr: null
    raft:
      enabled: true
      setNodeId: false
      config: |
        ui = true
        listener "tcp" {
          tls_disable = 1
          address = "[::]:8200"
          cluster_address = "[::]:8201"
        }
        storage "raft" {
          path = "/vault/data"
        }
        service_registration "kubernetes" {}

    disruptionBudget:
      enabled: true
      maxUnavailable: null

  serviceAccount:
    create: true
    name: ""
    createSecret: false
    annotations: {}
    extraLabels: {}
    serviceDiscovery:
      enabled: true

  statefulSet:
    annotations: {}
    securityContext:
      pod: {}
      container: {}

  hostNetwork: false

ui:
  enabled: true
  publishNotReadyAddresses: true
  activeVaultPodOnly: false
  serviceType: "ClusterIP"
  serviceNodePort: null
  externalPort: 8200
  targetPort: 8200
  serviceIPFamilyPolicy: ""
  serviceIPFamilies: []
  externalTrafficPolicy: Cluster
  annotations: {}

csi:
  enabled: true
  image:
    repository: "hashicorp/vault-csi-provider"
    tag: "1.5.1"
    pullPolicy: IfNotPresent
  volumes: null
  volumeMounts: null
  resources: {}
  hmacSecretName: ""
  hostNetwork: false
  daemonSet:
    updateStrategy:
      type: RollingUpdate
      maxUnavailable: ""
    annotations: {}
    providersDir: "/var/run/secrets-store-csi-providers"
    kubeletRootDir: "/var/lib/kubelet"
    extraLabels: {}
    securityContext:
      pod: {}
      container: {}
  pod:
    annotations: {}
    tolerations: []
    nodeSelector: {}
    affinity: {}
    extraLabels: {}
  agent:
    enabled: true
    extraArgs: []
    image:
      repository: "hashicorp/vault"
      tag: "1.20.4"
      pullPolicy: IfNotPresent
    logFormat: standard
    logLevel: info
    resources: {}
    securityContext:
      container:
        allowPrivilegeEscalation: false
        capabilities:
          drop:
            - ALL
        readOnlyRootFilesystem: true
        runAsNonRoot: true
        runAsUser: 100
        runAsGroup: 1000

  priorityClassName: ""
  serviceAccount:
    annotations: {}
    extraLabels: {}
  readinessProbe:
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 5
    successThreshold: 1
    timeoutSeconds: 3
  livenessProbe:
    failureThreshold: 2
    initialDelaySeconds: 5
    periodSeconds: 5
    successThreshold: 1
    timeoutSeconds: 3
  logLevel: "info"
  debug: false
  extraArgs: []

serverTelemetry:
  serviceMonitor:
    enabled: false
    selectors: {}
    interval: 30s
    scrapeTimeout: 10s
    tlsConfig: {}
    authorization: {}
    metricRelabelings: []
  prometheusRules:
      enabled: false
      selectors: {}
      rules: []
```

After installing the cluster with HA mode enabled, Vault is not initialized automatically. You must do this manually using the CLI.

To initialize Vault, connect to the main pod (`vault-0`):

```shell
kubectl exec -it vault-0 -n vault -- /bin/sh
```

Then execute the following commands:

```shell
export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_CLIENT_TIMEOUT=300s
vault operator init
```

You will receive several **Unseal Keys** and an **Initial Root Token**. Store this information in a safe place—without it, you will not be able to restore access to Vault.

Example output:

```shell
Unseal Key 1: 4ErPXwe87rjULP6yz7h3XZ8Dr/nhTyMrVLiIsQ8s5ksX
Unseal Key 2: IVk3hipR5D/yR5ngi1LJaaxRwarEWjR/hjC8DFwXuNYb
Unseal Key 3: qBCx+7B+wiehep0yArs7nVT73SyMYXh+AH3jCXTCs80H
Unseal Key 4: CQm+0tOTS9wZQWYJJU8Roo2tMCGS+dZt7eXMDLjU5gX+
Unseal Key 5: KTvyD+vhEXPNQgcQJQe69Gu/sjkhhl/ScGZNnmmN64xC

Initial Root Token: hvs.uKO8ZtmUgARVtrLhzBlQV4tA
```

By default, five keys are generated, and at least three of them are required to activate the storage.

After initialization, Vault is in a sealed state. To start the cluster, it needs to be unsealed.

To do this:

1.  Connect to each pod in turn (`vault-0`, `vault-1`, `vault-2`).
    
2.  Run the following commands, providing any three of the obtained keys:
    

```shell
vault operator unseal <UNSEAL_KEY_1>
vault operator unseal <UNSEAL_KEY_2>
vault operator unseal <UNSEAL_KEY_3>
```

3.  Check the status:
    

```shell
vault status
```

If everything was successful, the `Sealed` field will have the value `false`.

# Velero

Source: https://hostman.com/docs/kubernetes/addons/velero/

Velero is a tool for backing up, restoring, and migrating data in Kubernetes. It allows you to create backups, restore cluster states, and perform migrations between clusters.

To use Velero, you need to install the Velero CLI on your local machine and configure it in your Kubernetes cluster.

## Prerequisites

Before starting the installation, ensure you have:

-   Access to your Kubernetes cluster [configured](https://hostman.com/docs/kubernetes/connect-to-clusters/kubectl/) via `kubectl`.
-   An S3 bucket for storing backups. 

Create a separate namespace for Velero:

```shell
kubectl create namespace velero
```

## Creating an S3 Secret

To configure Velero's access to the S3 bucket, create a secret. Create a manifest file named `velero-credentials-secret.yaml` with the following content:

```yml
apiVersion: v1
kind: Secret
metadata:
  name: cloud-credentials
  namespace: velero
type: Opaque
stringData:
  cloud: |
    [default]
    aws_access_key_id=S3_Access_Key
    aws_secret_access_key=S3_Secret_Access_Key
```

Replace `S3_Access_Key` and `S3_Secret_Access_Key` with your S3 access credentials.

![Ccda87b0 981b 41db A72f Dd8785e459e0.png](https://content.hostman.com/assets/7846ed96-e927-4598-bab6-5e88b60cc6d8.png?width=1533&height=1233)

Apply the manifest:

```shell
kubectl apply -f velero-credentials-secret.yaml
```

Verify the secret creation:

```shell
kubectl describe secrets cloud-credentials -n velero
```

The `Data.cloud` value should not be empty.

## Installing Velero CLI

### Linux

Download the latest Velero release archive from the [official GitHub releases page](https://github.com/vmware-tanzu/velero/releases):

```shell
wget https://github.com/vmware-tanzu/velero/releases/download/v1.15.2/velero-v1.15.2-linux-amd64.tar.gz
```

Extract the archive:

```shell
tar -xvzf velero-v1.15.2-linux-amd64.tar.gz
```

Move the Velero binary to the `/usr/local/bin` directory:

```shell
sudo mv ./velero-v1.15.2-linux-amd64/velero /usr/local/bin/
```

### macOS

To install Velero on macOS, run:

```shell
brew install velero
```

### Windows

To install Velero on Windows using Chocolatey, run:

```shell
choco install velero
```

### Verify Installation

Check the installed version:

```shell
velero version
```

## Installing Velero in the Cluster

Create a `values.yaml` file with the minimum required configuration:

```yml
namespace:
  name: velero
  labels: {}

credentials:
  existingSecret: cloud-credentials

configuration:
  backupStorageLocation:
    - name: default
      provider: aws
      bucket: bucket_name
      default: true
      config:
        region: us-2
        s3ForcePathStyle: true
        s3Url: https://s3.hmstorage.net

  volumeSnapshotLocation:
    - name: default
      provider: aws
      config:
        region: us-2
initContainers:
  - name: velero-plugin-for-aws
    image: velero/velero-plugin-for-aws:v1.7.0
    volumeMounts:
      - mountPath: /target
        name: plugins
```

Parameter descriptions:

-   `backupStorageLocation`: Configures the backup storage.
-   `bucket`: The S3 bucket name.
-   `s3Url`: The Hostman S3 storage URL.
-   `initContainers`: Adds the required plugin for S3 integration.
-   `credentials.existingSecret`: Refers to the previously created `cloud-credentials` secret containing the S3 access keys.

### Via Dashboard

1.  Go to the **Kubernetes** section and click on the cluster.
2.  Navigate to the **Addons** tab and select **Velero**.
3.  Enable **Advanced setup** and upload the `values.yaml` file by clicking **Upload configuration from file**.
4.  Click **Install**.

![9b3c8b47 D00b 436b 804b 45455e420a6c](https://content.hostman.com/assets/84a300fe-2f1e-4d1c-8a04-7935eedcf2e2.png?width=1554&height=1093)

Wait for the installation to complete and check the pod status:

```shell
kubectl get pods -n velero
```

### Via Helm

You can install Velero using Helm.

1.  Add the Velero repository:
    

```shell
helm repo add velero https://vmware-tanzu.github.io/helm-charts
helm repo update
```

2.  Install Velero using the configuration file:
    

```shell
helm install velero velero/velero -f values.yaml --namespace velero
```

3.  Verify the installation:
    

```shell
kubectl get pods -n velero
```

The status of Velero pods should be `Running`.

## Usage

To demonstrate how Velero works, we will create a test deployment with Nginx and show the process of creating a backup, deleting resources, and then restoring the data.

### Creating a Backup

Create a deployment with Nginx in a separate namespace:

```shell
kubectl create namespace nginx-test
kubectl create deployment nginx --image=nginx -n nginx-test
```

Create a backup:

```shell
velero backup create nginx-backup --include-namespaces nginx-test
```

We specified the `--include-namespaces` parameter to back up the entire namespace. You can also specify other parameters when creating a backup:

-   `--include-resources`: Includes specific resources (e.g., `pods`, `services`).
-   `--exclude-resources`: Excludes specific resources.
-   `--ttl`: Sets the backup retention time (e.g., `10h15m0s`).

Check the backup status:

```shell
velero backup describe nginx-backup
```

### Restoring Data

Delete the test namespace:

```shell
kubectl delete namespace nginx-test
```

Restore resources from the backup:

```shell
velero restore create --from-backup nginx-backup
```

Ensure that the namespace and deployment have been restored:

```shell
kubectl get all -n nginx-test
```

## Managing Backup Schedules and Statuses

In addition to creating backups manually, Velero allows you to automate backup creation on a schedule. You can also manage existing backups.

### Configuring Automatic Backups

You can configure a schedule for regular backups. For example, to back up all namespaces every day at midnight:

```shell
velero schedule create task_name --schedule "0 0 * * *" --include-namespaces '*'
```

-   `--schedule "0 0 * * *"`: Cron format schedule (every day at 00:00).
-   `--include-namespaces '*'`: Includes all namespaces.

To create backups for a single namespace every hour:

```shell
velero schedule create task_name --schedule "0 * * * *" --include-namespaces my-namespace
```

Check the backup schedule with:

```shell
velero schedule get
```

If a scheduled task is no longer needed, delete it with:

```shell
velero schedule delete task_name
```

### Viewing and Managing Backups

List all existing backups:

```shell
velero backup get
```

To delete an old backup, use:

```shell
velero backup delete backup_name
```

To check backup details, including its status and resources:

```shell
velero backup describe backup_name --details
```

These features provide flexible backup management and allow data restoration whenever needed.

# VictoriaMetrics Operator

Source: https://hostman.com/docs/kubernetes/addons/victoriametrics-operator/

VictoriaMetrics Operator is a Kubernetes operator that automates the deployment and management of monitoring components based on VictoriaMetrics. It allows you to create and configure individual services for collecting, storing, and visualizing metrics.

The operator uses CRDs (Custom Resource Definitions) to manage monitoring infrastructure. The main components include:

-   **VMSingle** — a single-instance VictoriaMetrics component responsible for storing metrics. It’s suitable for simple projects and low-traffic clusters.
-   **VMCluster** — a scalable setup with storage replicas and proxy components. Best suited for production and high-volume environments.
-   **VMAgent** — collects metrics from pods, services, and other sources, then sends them to VMSingle or VMCluster via remoteWrite.
-   **VMPodScrape** — a CRD object that defines which pods should be scraped for metrics, and on what addresses/ports.

Full documentation for VictoriaMetrics Operator is available on the [official website](https://docs.victoriametrics.com/operator/).

## Installation

To install VictoriaMetrics Operator:

1.  Go to the **Kubernetes** section and select your cluster.
2.  On the **Addons** tab, click **VictoriaMetrics Operator**.
3.  In the configuration window, you can optionally adjust parameters, such as setting a custom namespace, changing component versions, or disabling unnecessary CRDs.
4.  After configuration, click **Install**.

Once installed, the cluster will include the `victoria-metrics-operator` namespace and all necessary CRDs, including `VMSingle`, `VMAgent`, `VMPodScrape`, and others. To list them, run:

```shell
kubectl get crd | grep 'vm'
```

## Usage Example

In this example, we will:

1.  Deploy a VMSingle instance to store metrics.
2.  Set up a VMAgent to collect metrics from sources.
3.  Launch a pod with Nginx and `nginx-prometheus-exporter` to expose metrics.
4.  Create a VMPodScrape object to allow VMAgent to collect those metrics.
5.  Configure Ingress to access the VictoriaMetrics web UI.

You’ll need the [Nginx Ingress](https://hostman.com/docs/kubernetes/addons/nginx-ingress/) addon installed in your cluster for this example.

#### Step 1: Create VMSingle

This component will accept and store metrics. In the example, it’s configured with minimal resource requirements and stores data in memory for 1 day.

Create a file called `vmsingle.yaml` with the following configuration.

```yaml
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMSingle
metadata:
  name: vm-single
  namespace: victoria-metrics-operator
spec:
  retentionPeriod: "1"
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
```

#### Step 2: Create VMAgent

This agent will collect metrics and forward them to VMSingle. Create a file named `vmagent.yaml`:

```yaml
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMAgent
metadata:
  name: vmagent
  namespace: victoria-metrics-operator
spec:
  remoteWrite:
    - url: http://vmsingle-vm-single.victoria-metrics-operator:8428/api/v1/write
  scrapeInterval: 30s
  selectAllByDefault: true
  port: "8429"
```

#### Step 3: Deploy Nginx and Exporter

Launch a pod with Nginx and `nginx-prometheus-exporter`, which will expose metrics via `/stub_status`.

Create a file called `nginx.yaml`:

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  namespace: victoria-metrics-operator
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - name: nginx
          image: nginx:1.25
          ports:
            - containerPort: 80
              name: http
          volumeMounts:
            - name: nginx-conf
              mountPath: /etc/nginx/conf.d/default.conf
              subPath: default.conf
        - name: exporter
          image: nginx/nginx-prometheus-exporter:1.1.0
          args:
            - "-nginx.scrape-uri=http://localhost/stub_status"
          ports:
            - containerPort: 9113
              name: metrics
      volumes:
        - name: nginx-conf
          configMap:
            name: nginx-conf
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: nginx-conf
  namespace: victoria-metrics-operator
data:
  default.conf: | server { listen 80; location / { return 200 'OK'; } location /stub_status { stub_status; allow 127.0.0.1; deny all; } } ---
apiVersion: v1
kind: Service
metadata:
  name: nginx
  namespace: victoria-metrics-operator
spec:
  selector:
    app: nginx
  ports:
    - name: http
      port: 80
      targetPort: http
    - name: metrics
      port: 9113
      targetPort: metrics
```

#### Step 4: Configure VMPodScrape

This object tells VMAgent which pods to scrape metrics from. It will target pods with the label `app: nginx` and query the `metrics` port at `/metrics`.

Create a file named `vmpodscrape.yaml`:

```yaml
apiVersion: operator.victoriametrics.com/v1beta1
kind: VMPodScrape
metadata:
  name: nginx-scrape
  namespace: victoria-metrics-operator
spec:
  selector:
    matchLabels:
      app: nginx
  podMetricsEndpoints:
    - port: metrics
      path: /metrics
      interval: 30s
```

#### Step 5: Set Up Ingress for UI

Before configuring Ingress, ensure your cluster has a service of type LoadBalancer for external access. You can check with:

```shell
kubectl get svc -n ingress-nginx
```

If none is present, create it:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-loadbalancer
  namespace: ingress-nginx
spec:
  selector:
    app.kubernetes.io/name: ingress-nginx
  ports:
    - port: 80
      targetPort: 80
      appProtocol: k8s.hostman.com/proto-http
  type: LoadBalancer
```

After creation, retrieve the external IP:

```shell
kubectl get svc -n ingress-nginx nginx-loadbalancer
```

Use that IP as an A record for the domain where you want the VictoriaMetrics UI to be accessible.

#### Step 6: Create Ingress for VictoriaMetrics UI

Specify the domain in the host field of your Ingress manifest. Create a file called `vm-ui-ingress.yaml`:

```yaml
apiVersion: v1
kind: Service
metadata:
  name: nginx-loadbalancer
  namespace: ingress-nginx
spec:
  selector:
    app.kubernetes.io/name: ingress-nginx
  ports:
    - port: 80
      targetPort: 80
      appProtocol: k8s.hostman.com/proto-http
  type: LoadBalancer
```

Apply all the created manifests:

```shell
kubectl apply -f vmsingle.yaml
kubectl apply -f vmagent.yaml
kubectl apply -f nginx.yaml
kubectl apply -f vmpodscrape.yaml
kubectl apply -f vm-ui-ingress.yaml
```

#### Accessing the UI

Navigate to the domain specified in your Ingress (e.g., `http://vm.example.com`). 

Once there:

1.  Select **vmui** to open the VictoriaMetrics web interface.
2.  In the **query** field, type a metric name, such as **up**, and click **Execute Query**.
3.  If everything is configured correctly, you’ll see metrics being collected from the Nginx pod.

![0c8b8536 6b4e 4adf Be8a 9296ea98cc4b.png](https://content.hostman.com/assets/db3ce133-e84c-44a3-bbe7-3fc02a4d26d0.png?width=2894&height=1600)

_The "Query" section in the [VictoriaMetrics](https://victoriametrics.com/) interface_

# Helm

Source: https://hostman.com/docs/kubernetes/applications/

-   [Manage Applications with Helm](https://hostman.com/docs/kubernetes/applications/helm/)
-   [Create Helm Charts](https://hostman.com/docs/kubernetes/applications/helm-charts/)

# Manage Applications with Helm

Source: https://hostman.com/docs/kubernetes/applications/helm/

Helm is a tool for managing Kubernetes applications, simplifying the deployment, updating, and maintenance of complex applications that consist of multiple Kubernetes objects. Essentially, Helm can be compared to a package manager for Kubernetes, similar to `apt` or `yum` in Linux, but specifically adapted for managing [Kubernetes clusters](https://hostman.com/products/kubernetes/).

Helm addresses several key tasks:

-   **Simplified Deployment**

Applications can be made up of dozens or even hundreds of Kubernetes objects, such as pods, services, configurations, and more. Helm consolidates these into a single package called a **chart**, which can be deployed with a single command. This approach significantly reduces the complexity of manually configuring applications.

-   **Version Control for Applications**

Each chart can have multiple versions, making it easy to roll back to a previous version or update an application. Helm supports version control, tracks changes in deployed applications (releases), and allows rollbacks when necessary.

-   **Reusable Configurations**

Helm uses templates to generate Kubernetes configuration files, simplifying the customization of parameters such as the number of replicas, network access settings, databases, and other variables. These settings are stored in a special configuration file `values.yaml`. This allows the same chart to be used across different environments (development, testing, production) with minimal modifications.

-   **Centralized Repository Management**

Charts are stored in repositories, which can be either public or private. Helm allows adding, updating, and installing applications directly from different repositories. For example, the popular Bitnami repository contains many ready-to-use charts for various services.

## Installing Helm

> [!NOTE]
> Helm is closely tied to the [Kubernetes](https://hostman.com/products/kubernetes/) version, so it’s essential to **choose a version compatible with your cluster.** You can refer to the Helm and Kubernetes compatibility table in the [official documentation](https://helm.sh/docs/topics/version_skew/#supported-version-skew).

### Linux

To install Helm on Linux, you can use the official script for automated installation:

1.  Download the installation script and make it executable:
    

```shell
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 && chmod 700 get_helm.sh
```

2.  Run the script to install the latest version of Helm:
    

```shell
./get_helm.sh
```

3.  Specify a Helm version compatible with your Kubernetes cluster::
    

```shell
./get_helm.sh -v 3.14.1
```

#### Installation via Repository on Ubuntu

To install Helm through the system package manager on Ubuntu, follow these steps:

1.  Add the Helm repository signing key:
    

```shell
curl https://baltocdn.com/helm/signing.asc | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
```

2.  Install the `apt-transport-https` package if it’s not already installed:
    

```shell
sudo apt install apt-transport-https --yes
```

3.  Add the Helm repository to your APT sources:
    

```shell
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/helm.gpg] https://baltocdn.com/helm/stable/debian/ all main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
```

4.  Update your package list:
    

```shell
sudo apt update
```

5.  Install Helm:
    

```shell
sudo apt install helm
```

6.  Specify a Helm version compatible with your Kubernetes cluster:
    

```shell
sudo apt install helm=3.14.2-1
```

7.  Verify the installation:
    

```shell
helm version
```

### Windows

To install Helm on Windows, follow these steps:

1.  Run PowerShell as Administrator.
    
2.  Install Helm with the following command:
    

```shell
winget install Helm.Helm
```

3.  Install a Helm version compatible with your Kubernetes cluster:
    

```shell
winget install Helm.Helm -v 3.14.1
```

4.  Verify the Helm version:
    

```shell
helm version
```

### MacOS

To install Helm on MacOS, you can use the official automated installation script:

1.  Download the installation script and make it executable:
    

```shell
curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 && chmod 700 get_helm.sh
```

2.  Run the script to install the latest Helm version:
    

```shell
./get_helm.sh
```

3.  Specify a Helm version compatible with your Kubernetes cluster:
    

```shell
./get_helm.sh -v 3.14.1
```

#### Installation via Homebrew

If you use Homebrew, you can install Helm with it. Note that only the latest version of Helm is available in Homebrew repositories. To install, run:

```shell
brew install helm
```

Verify the Helm version:

```shell
helm version
```

## Setting Up Helm Repositories

Helm uses repositories to store and distribute charts — application packages that can be installed in Kubernetes. Repositories help manage applications from centralized sources, simplifying the processes of installing, updating, and removing applications.

### Adding a Repository

To install an application from a remote repository, you first need to add it to the list of available sources. This is done using the `helm repo add` command. For example, to add the popular Bitnami repository, run the following command:

```shell
helm repo add bitnami https://charts.bitnami.com/bitnami
```

Helm supports both public and private repositories. Private repositories may require authentication credentials, such as a token or a username and password.

### Updating Repositories

Charts in repositories may be updated, so to ensure you have the latest versions, it’s necessary to periodically update repository information. Use the following command:

```shell
helm repo update
```

This command synchronizes your local chart index with the current content of remote repositories.

### Viewing Available Repositories

You can view a list of all connected repositories with this command:

```shell
helm repo list
```

Example output:

![Image2](https://content.hostman.com/assets/3b891da9-f207-45e6-94a3-945d3cace084.png?width=681&height=188)

### Removing a Repository

If a repository is no longer needed, you can remove it using the `helm repo remove` command. For example, to remove the Bitnami repository, run:

```shell
helm repo remove bitnami
```

This command only removes the repository from your local Helm configuration. The charts and installed applications themselves are not affected.

## Installing Applications with Helm

After setting up repositories, you can search for and install applications in Kubernetes using Helm.

### Searching for Applications in Repositories

To find a specific chart in connected repositories, use the following command:

```shell
helm search repo <application_name>
```

For example, to search for NGINX, run:

```shell
helm search repo nginx
```

### Installing an Application

To install an application, use this command:

```shell
helm install <release_name> <repository>/<chart_name>
```

For example, to install NGINX from the Bitnami repository:

```shell
helm install my-nginx bitnami/nginx
```

### Checking the Status of an Installed Application

To check the application’s status, use:

```shell
kubectl get pods
```

To get release-specific information:

```shell
helm status <release_name>
```

### Overriding Installation Parameters

To customize chart parameters, use:

```shell
helm install my-nginx bitnami/nginx --set service.type=NodePort
```

### Uninstalling an Application

To remove an application and its resources, run:

```shell
helm uninstall <release_name>
```

# Create Helm Charts

Source: https://hostman.com/docs/kubernetes/applications/helm-charts/

Helm charts allow you to package [Kubernetes](https://hostman.com/products/kubernetes/) applications into a convenient bundle that includes all necessary resources for deployment and management. Charts automate the creation, updating, and deletion of applications in Kubernetes, making them easier and more flexible to manage.

## Creating a New Chart

To create a new chart, use the following command:

```shell
helm create <chart_name>
```

Helm will automatically generate a basic directory structure and files containing the necessary templates and configurations for deploying the application in Kubernetes.

## Key Files and Directories

#### Chart.yaml

The main file of the chart containing metadata: name, version, description, and application version. It can also include dependency information if the application relies on other charts.

Usage Example:

-   Specifies which application is being deployed and its version.
-   Simplifies chart version management and change tracking.

#### values.yaml

A file with default parameters used to set values applied to chart templates for generating the final Kubernetes manifests.

Usage Example:

-   Defines parameters such as replica count, service type, and container image.
-   Allows overriding values via the `--set` flag or an additional file during installation.

#### templates/

This directory contains YAML templates for Kubernetes files that define objects (pods, deployments, services, etc.) that will be created when the chart is installed. Templates use the Go language to dynamically generate manifests based on values from `values.yaml`.

Usage Example:

-   Templates for creating Kubernetes objects (e.g., `deployment.yaml`, `service.yaml`).
-   Logic for flexible resource configuration (e.g., replica count or service type).

#### charts/

A directory for dependencies, i.e. other charts required for your application to run. Dependencies can be installed locally or downloaded from remote repositories.

Usage Example:

-   Dependencies are downloaded with `helm dependency update` if specified in `Chart.yaml`.
    

#### .helmignore

This file functions like `.gitignore`, excluding files and directories when packaging the chart into an archive.

Usage Example:

-   Excludes unnecessary files (e.g., documentation or temporary files) to keep them out of the final package.
    

Now that we’ve reviewed the basic structure of a chart and the purpose of the key files, let’s move on to a practical example. We’ll create a chart for deploying NGINX, configure all the necessary parameters, and see how templates use data from values.yaml to generate Kubernetes resources.

## Creating the Chart Basic Structure

Start by creating the basic structure of the chart. Enter the command:

```shell
helm create nginx-chart
```

This will create a directory `nginx-chart/` with the basic files.

```shell
nginx-chart
├── charts
├── Chart.yaml
├── templates
│   ├── deployment.yaml
│   ├── _helpers.tpl
│   ├── hpa.yaml
│   ├── ingress.yaml
│   ├── NOTES.txt
│   ├── serviceaccount.yaml
│   ├── service.yaml
│   └── tests
│   	└── test-connection.yaml
└── values.yaml
```

## Configuring the Chart.yaml File

The `Chart.yaml` file is a key element of any Helm chart. This file specifies metadata for the chart, such as its name, version, description, and information about dependencies.

Example of the `Chart.yaml` content for the NGINX chart:

```yml
apiVersion: v2       	
name: nginx-chart    	
description: A Helm chart for deploying NGINX  
version: 0.1.0       	
appVersion: "1.21.0"
```

Key fields:

-   `apiVersion`: The Helm API version for this chart. Use `v2` for Helm 3 charts.
-   `name`: The name of your chart. This should be unique in your repository.
-   `description`: A brief description of what this chart does.
-   `version`: The version of the chart itself. Each time you make changes to the chart, you should update this version.
-   `appVersion`: The version of the application (in this case, NGINX) that will be deployed. This field does not affect Helm’s logic but helps users see which version of the application they are installing.

## Configuring the values.yaml File

The `values.yaml` file is used to specify default values for parameters that can be changed during chart installation. Configure it as follows:

```yml
replicaCount: 2

image:
  repository: nginx
  tag: "1.21.0"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

serviceAccount:
  create: true
  name: ""

ingress:
  enabled: false
  annotations: {}
  hosts:
	- host: chart-example.local
  	paths: []
  tls: []

autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 5
  targetCPUUtilizationPercentage: 80

resources: {}

nodeSelector: {}

tolerations: []

affinity: {}
```

This file contains the following settings:

-   `replicaCount`: The number of application replicas.
-   `image`: Settings for the NGINX container image, including the version (`tag`).
-   `service`: The type of service and the port through which NGINX will be accessible.
-   `serviceAccount`: Creates a service account for the chart.
-   `ingress`: Parameters for Ingress (disabled by default).
-   `autoscaling`: Parameters for auto-scaling (disabled by default).

## Chart Templates

Next, let’s configure the templates in the `templates` folder that will use values from `values.yaml`.

#### templates/service.yaml

A template for creating a [Kubernetes service](https://hostman.com/products/kubernetes/):

```yml
apiVersion: v1
kind: Service
metadata:
  name: {{ include "nginx-chart.fullname" . }}
  labels:
	app: {{ include "nginx-chart.name" . }}
spec:
  type: {{ .Values.service.type }}
  ports:
	- port: {{ .Values.service.port }}
  	targetPort: 80
  selector:
	app: {{ include "nginx-chart.name" . }}
```

#### templates/deployment.yaml

A template for creating an NGINX deployment:

```yml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "nginx-chart.fullname" . }}
  labels:
	app: {{ include "nginx-chart.name" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
	matchLabels:
  	app: {{ include "nginx-chart.name" . }}
  template:
	metadata:
  	labels:
    	app: {{ include "nginx-chart.name" . }}
	spec:
  	serviceAccountName: {{ if .Values.serviceAccount.create }}{{ include "nginx-chart.serviceAccountName" . }}{{ else }}{{ .Values.serviceAccount.name }}{{ end }}
  	containers:
    	- name: nginx
      	image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
      	ports:
        	- containerPort: 80
```

#### templates/serviceaccount.yaml

A template for creating a service account:

```yml
{{- if .Values.serviceAccount.create }}
apiVersion: v1
kind: ServiceAccount
metadata:
  name: {{ include "nginx-chart.serviceAccountName" . }}
{{- end }}
```

## Chart Verification and Installation

Check the chart for errors:

```shell
helm lint ./nginx-chart
```

Install the chart:

```shell
helm install test-nginx ./nginx-chart
```

Check the release status:

```shell
helm status test-nginx
```

Check the state of the pods:

```shell
kubectl get pods
```

## Chart Removal

When the application is no longer needed, it can be removed:

```shell
helm uninstall test-nginx
```

# Users and Access

Source: https://hostman.com/docs/kubernetes/access/

-   [OIDC Provider Setup](https://hostman.com/docs/kubernetes/access/oidc-provider-setup/)
-   [Managing User Access](https://hostman.com/docs/kubernetes/access/managing-user-access/)

# OIDC Provider Setup

Source: https://hostman.com/docs/kubernetes/access/oidc-provider-setup/

OpenID Connect (OIDC) is an authentication protocol built on top of OAuth 2.0. It allows you to configure user authentication in a Kubernetes cluster using authentication services such as Google, Keycloak, Dex, GitHub, and others.

## Setting Up the OIDC Provider

You can configure the OIDC provider when creating a cluster in the step **5\. OIDC Provider**:

![2d16ba1e 08c3 455d 9fa4 2a37be0b84a4](https://content.hostman.com/assets/567b9a59-b091-4e4d-80f8-db71c08afc16.png?width=624&height=664)

Or later via the **Management** section:

![7501ec4f A753 4e3c 8311 82d35b2e4801](https://content.hostman.com/assets/b3d6331e-4dd7-41aa-a9f2-ab32f37bd791.png?width=1383&height=869)

During setup, specify the following values:

-   **Connection Name** (required): The display name for the connection, shown only in the dashboard, does not affect OIDC operation.
-   **Issuer URL** (required): The OIDC provider address. For example:  
    -   `https://<domain>/realms/<realm>` for Keycloak
    -   `https://accounts.google.com` for Google
-   **Client ID** (required): The client ID registered with the OIDC provider.
-   **Username Claim**: Field in the ID token to be used by Kubernetes as the username (e.g., `sub`, `preferred_username`, or `email`).
-   **Groups Claim**: Field in the ID token containing the list of user groups. Used for group-based RBAC access control.

After entering the necessary parameters, click **Save**.

## Installing kubelogin

The `kubelogin` utility is used to obtain an ID token from the provider and pass it to Kubernetes when executing commands via `kubectl`.

#### Linux

Download the archive with the latest version of the utility:

```shell
curl -LO https://github.com/int128/kubelogin/releases/latest/download/kubelogin_linux_amd64.zip
```

Unzip the archive:

```shell
unzip kubelogin_linux_amd64.zip
```

Make the binary executable:

```shell
chmod +x kubelogin
```

Move it to a system path so it can be run from any directory:

```shell
sudo mv kubelogin /usr/local/bin/
```

#### macOS

Install with Homebrew:

```shell
brew install kubelogin
```

#### Windows

Install with Chocolatey:

```shell
choco install kubelogin
```

#### Krew

If you use Krew, `kubectl` plugin manager, run the command:

```shell
kubectl krew install oidc-login
```

## Getting a Token

Run the following command:

```shell
kubelogin get-token \
  --oidc-issuer-url=https://oidc-provider-address \
  --oidc-client-id=client_id \
  --oidc-client-secret=secret
```

A browser window will open prompting you to log in. After successful authentication, a token in JSON format will be displayed. For example:

```shell
{"kind":"ExecCredential","apiVersion":"client.authentication.k8s.io/v1beta1","spec":{"interactive":false},"status":{"expirationTimestamp":"2025-04-24T08:48:30Z","token":"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJ3X3AxNzlsdkkzTnltWW01M09GZEpWeDJGeGJ6cGxoX2s5OHVFcmtjRmY4In0.eyJleHAiOjE3NDU0ODQ1MTAsImlhdCI6MTc0NTQ4NDQ1MSwiYXV0aF90aW1lIjoxNzQ1NDg0NDUwLCJqdGkiOiJkNTVmYjkzMy0zY2NlLTRkODYtYTcxZS1lNzc1ODZkN2E2ZGIiLCJpc3MiOiJodHRwczovL2tleWNsb2FrLm5kb2xnaWtoLnNpdGUvcmVhbG1zL21hc3RlciIsImF1ZCI6InRlc3QiLCJzdWIiOiIyY2U5NDk5Ni0zN2NlLTQ1NDEtOGFiOS00ZTk0MWE2YjhmYW123eXAiOiJJRCIsImF6cCI6InRlc3QiLCJub25jZSI6InhuWGNLMTlIVUprRTB0N3BXbVJ6NXJBWC0ya0h4NFpVaGdhbEJ2OW1QsfaiLCJzZXNzaW9uX3N0YXRlIjoiYjZmOWRmNmMtMjNhMS00OGU4LTkwMDQtOWJlYmFmNzY0OGU4IiwiYXRfaGFzaCI6IldocDAtQkdCTmhWNTUwc082eW9wS2ciLCJhY3IiOiIxIiwic2lkIjoiYjZmOWRmNmMtMjNhMS00OGU4LTkwMDQtOWJlYmFmNzY0OGU4IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJuYW1lIjoidGVzdCB0ZXN0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoidGVzdEBtYWlsLnJ1IiwiZ2l2ZW5fbmFtZSI6InRlc3QiLCJmYW1pbHlfbmFtZSI6InRlc3QiLCJlbWFpbCI6InRlc3RAbWFpbC5ydSJ9.GQjRT_gTjsdfuVwhPYCW5DlqL_pbXpiYItIxNvOs9G8jUldV-3LyntQa4Zf4OSwzKldiJ4wZDRa-8pGI-BwD3SO1RxhkbYm_yTFxXDguxNdjstrFcCfLaslhBPqelpKC7DbsIqSLRIoixihPynIEMhEZRxvlDwZuYmWwyn7zMztQyGHPam_ujICIddcODBDBHA2Ksw_ZNwMAoU0sdMlI3fjTJst_Mh3jgzQRpFctc7X75JCL37HcZ6HBb6_9SWfmKHGO3ivFGs1pKtX6XDay8zt65DaEKM41iTjCzr-nKQ1Qk16fRypgsUauSJp_UHiGMiAUHSz66hQdvUr1uByg"}}
```

To decode and view the token payload, use:

```shell
echo "token" | cut -d '.' -f2 | base64 -d | jq
```

Example output:

```shell
 {
  "exp": 1745480015,
  "iat": 1745479955,
  "auth_time": 1745479955,
  "jti": "4d9d243a-f62d-4150-94eb-5c535d2c0ea8",
  "iss": "https://keycloak.hostman.com/realms/master",
  "aud": "test-user",
  "sub": "2ce94996-37ce-4541-8ab9-4e941a6b8faa",
  "typ": "ID",
  "azp": "test-user",
  "nonce": "ubNzQ6KRI746Ab1WPGG3Z5tONUPDPx-sSud4aLKDlT4",
  "session_state": "e0933444-3a04-4e17-885c-1a7f93e0ebb3",
  "at_hash": "QpL9mrseqRikRIVEhdQrBQ",
  "acr": "1",
  "sid": "e0933444-3a04-4e17-885c-1a7f93e0ebb3",
  "email_verified": false,
  "name": "Hostman",
  "preferred_username": "test@example.com",
  "given_name": "test",
  "family_name": "test",
  "email": "test@example.com"
}
```

The name of the claim you configured as the "Username claim" will appear here (default is `sub`).

## Configuring RBAC

RBAC (Role-Based Access Control) is a mechanism in Kubernetes that manages user permissions. It is used to define which resources a user can view or modify. You can find more details in the [official documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/).

To configure RBAC, create a manifest file named `oidc-access.yaml` with the following content:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: keycloak-cluster-role
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: keycloak-cluster-role-binding
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: keycloak-cluster-role
subjects:
  - kind: User
    name: "https://oidc-provider#sub"
    apiGroup: rbac.authorization.k8s.io
```

Specify the value of the `sub` field from the token in the `name` parameter. This will grant full (`cluster-admin`) access to the specific user authenticated via OIDC.

Apply the manifest:

```shell
kubectl apply -f oidc-access.yaml
```

If you want to grant read-only access to resources, for example, to pods in the `default` namespace, apply the following manifest:

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: readonly-pods
  namespace: default
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: readonly-pods-binding
  namespace: default
roleRef:
  kind: Role
  name: readonly-pods
  apiGroup: rbac.authorization.k8s.io
subjects:
  - kind: User
    name: "https://oidc-provider#sub"
    apiGroup: rbac.authorization.k8s.io
```

If you specified a “Username claim” with a value such as `preferred_username` when setting up the OIDC provider in the dashboard, Kubernetes will use it as the username. In this case, you can simplify `subjects.name` and use a readable name, for example:

```yaml
subjects:
  - kind: User
    name: "test@example.com"
    apiGroup: rbac.authorization.k8s.io
```

## Configuring kubectl to Use OIDC

Add the OIDC user to your `kubeconfig` to connect to the cluster via OIDC:

```shell
kubectl config set-credentials oidc \
  --exec-api-version=client.authentication.k8s.io/v1 \
  --exec-interactive-mode=IfAvailable \
  --exec-command=kubelogin \
  --exec-arg=get-token \
  --exec-arg=--oidc-issuer-url=https://oidc-provider-address \
  --exec-arg=--oidc-client-id=client_id \
  --exec-arg=--oidc-client-secret=secret
```

Set the current context to use this user:

```shell
kubectl config set-context --current --user=oidc
```

Verify:

```shell
kubectl get pods
```

A browser window will prompt for login. After successful authentication, the command should run without errors. If access is denied, check the RBAC rules.

If everything works fine, you can exclusively use OIDC and disable certificate-based auth. To do this, comment out or remove the certificate credentials from `kubeconfig`:

```shell
# - name: xg60398-1032513
#   user:
# client-certificate-data: LS0tLS1CRUdJTiBD…
# client-key-data: LS0tLS1CRUdJ…
```

## Disabling the OIDC Provider

To disable the OIDC provider:

1.  Go to the Kubernetes section
2.  Click on the cluster and go to the **Management** tab.
3.  Click **Edit** next to the **OIDC provider**.
4.  Click **Delete**.

After removal, all users authenticated via OIDC will lose access. However, RBAC rules will remain and must be removed manually.

To find linked role bindings:

```shell
kubectl get rolebindings --all-namespaces -o yaml | grep -B5 https://oidc-provider-address
```

To delete them:

```shell
kubectl delete clusterrolebinding <name>
```

To restore access, if `kubeconfig` was set up for OIDC, revert to the certificate-based authentication settings or download the `kubeconfig` from the dashboard.

# Manage User Access

Source: https://hostman.com/docs/kubernetes/access/managing-user-access/

In Kubernetes clusters, access control is handled natively by Kubernetes itself. The `kubeconfig` file you download from the dashboard contains administrative credentials and is suitable for initial cluster setup.

If multiple team members need access to the same cluster, sharing a single admin `kubeconfig` is not a good practice. If that file is leaked or stays with a former employee, there is no way to revoke access for just that one person. The safer approach is to create a separate account for each user and grant the necessary permissions through RBAC.

This guide covers how to set up per-user access using a `ServiceAccount`, a `RoleBinding` or `ClusterRoleBinding`, and a dedicated `kubeconfig` with a token.

## Prerequisites

You will need a running Kubernetes cluster, the admin `kubeconfig` downloaded from the dashboard, and [kubectl](https://hostman.com/docs/kubernetes/connect-to-clusters/kubectl/) installed.

To download the `kubeconfig`, go to the Kubernetes cluster management page in the dashboard. On the Dashboard tab, click the "download configuration file" link. The downloaded file will be named `twc-cluster_name.yaml`.

![Charming Grosbeak 05 22 2026 01 28 Pm](https://content.hostman.com/assets/cf290d1b-0319-4c92-b9a1-c0bf2d1fbdd4.png?width=1557&height=863)

Verify connectivity to the cluster:

```shell
kubectl --kubeconfig=twc-cluster_name.yaml get nodes
```

If the command returns a list of nodes, you are ready to create user accounts.

## Create a Namespace for User Accounts

It is convenient to manage all user accounts in a dedicated namespace, for example `kube-users`:

```shell
kubectl create namespace kube-users
```

We will create a `ServiceAccount` for the user `newuser`:

```shell
kubectl create serviceaccount newuser -n kube-users
```

This account name will be used when assigning permissions and generating tokens.

## Grant Permissions

Permissions in Kubernetes are managed through RBAC using two resource types:

-   `RoleBinding` grants permissions within a single namespace
-   `ClusterRoleBinding` grants permissions across the entire cluster

Always follow the principle of least privilege. If a user only needs access to one namespace, use a `RoleBinding` rather than a `ClusterRoleBinding`.

### Access to a Single Namespace

To restrict a user to a single namespace, create a `RoleBinding` in that namespace. The example below grants `newuser` edit permissions in the app-prod namespace:

```shell
kubectl create namespace app-prod
 
kubectl create rolebinding newuser-app-prod-edit \
  --namespace app-prod \
  --clusterrole edit \
  --serviceaccount kube-users:newuser
```

You can replace edit with any other built-in role:

| **Role** | **Description** |
| --- | --- |
| `view` | Read-only access to resources in the namespace. |
| `edit` | Create and modify most resources in the namespace. |
| `admin` | Full management of namespace resources, including roles and role bindings. |
| `cluster-admin` | Full administrative access to the entire cluster. |

These are the standard Kubernetes `ClusterRoles`. If none of them fit your requirements, you can [create custom ClusterRoles](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#kubectl-create-clusterrole) with specific rules.

To verify that permissions were applied correctly:

```shell
kubectl auth can-i create deployments \
  --as system:serviceaccount:kube-users:newuser \
  -n app-prod
```

If access is configured correctly, the command returns:

```shell
yes
```

### Access to the Entire Cluster

If a user needs full administrative access to the cluster, create a `ClusterRoleBinding`:

```shell
kubectl create clusterrolebinding newuser-cluster-admin \
  --clusterrole cluster-admin \
  --serviceaccount kube-users:newuser
```

Only assign the `cluster-admin` role to cluster administrators. For development teams, namespace-scoped access is a safer default.

## Create a Token

Users need a token to connect with `kubectl`. Kubernetes supports two token types: short-lived tokens and long-lived tokens stored in a `Secret`.

### Short-Lived Token

Create a short-lived token using `kubectl create token`. The example below generates a token valid for 24 hours:

```shell
TOKEN=$(kubectl create token newuser -n kube-users --duration=24h)
```

View the token value:

```shell
echo "${TOKEN}"
```

The token will stop working automatically after the expiry time.

Short-lived tokens do not create any object in the cluster, so there is no way to revoke a specific token before it expires. If you need to cut off access immediately, delete the user's permissions or the `ServiceAccount` itself.

### Long-Lived Token

If you need a token without an expiry, create a `Secret` of type `kubernetes.io/service-account-token`. You can revoke this token at any time by deleting the `Secret`.

Create a file named `newuser-token-secret.yaml`:

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: newuser-token
  namespace: kube-users
  annotations:
    kubernetes.io/service-account.name: newuser
type: kubernetes.io/service-account-token
```

Apply the manifest:

```shell
kubectl apply -f newuser-token-secret.yaml
```

Retrieve the token value:

```shell
TOKEN=$(kubectl get secret newuser-token \
  -n kube-users \
  -o jsonpath='{.data.token}' | base64 -d)
```

Only use long-lived tokens where short-lived tokens are not practical. Treat them as sensitive credentials and store them accordingly.

## Create a kubeconfig for the User

Create a separate `kubeconfig` file that contains the cluster connection details and the `newuser` token.

First, retrieve the cluster parameters from the admin `kubeconfig`:

```shell
CLUSTER_NAME=$(kubectl config view --minify -o jsonpath='{.clusters[0].name}')
CLUSTER_SERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
kubectl config view --raw --minify -o jsonpath='{.clusters[0].cluster.certificate-authority-data}' | base64 -d > ca.crt
```

Create the new configuration file:

```shell
kubectl config --kubeconfig=newuser.kubeconfig set-cluster "${CLUSTER_NAME}" \
  --server="${CLUSTER_SERVER}" \
  --certificate-authority=ca.crt \
  --embed-certs=true
 
kubectl config --kubeconfig=newuser.kubeconfig set-credentials newuser \
  --token="${TOKEN}"
 
kubectl config --kubeconfig=newuser.kubeconfig set-context newuser-context \
  --cluster="${CLUSTER_NAME}" \
  --user=newuser
 
kubectl config --kubeconfig=newuser.kubeconfig use-context newuser-context
```

If the user should work in a specific namespace by default, add it to the context:

```shell
kubectl config --kubeconfig=newuser.kubeconfig set-context newuser-context \
  --cluster="${CLUSTER_NAME}" \
  --user=newuser \
  --namespace=app-prod
```

Once the file is ready, you can hand `newuser.kubeconfig` over to the user.

#### Example kubeconfig

Below is an example of a user `kubeconfig` using token-based authentication. The values for `certificate-authority-data`, `server`, and `token` will be different in your cluster.

```yaml
apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <CA_DATA>
    server: https://<API_SERVER>:6443
  name: twc-example-cluster
contexts:
- context:
    cluster: twc-example-cluster
    namespace: app-prod
    user: newuser
  name: newuser-context
current-context: newuser-context
kind: Config
preferences: {}
users:
- name: newuser
  user:
    token: <TOKEN>
```

The final file must not contain the admin user, client certificate, or private key from the original `kubeconfig`. Before sharing the file, verify that the users section contains only the user's token-based account.

## Verify Access

Test the new `kubeconfig`:

```shell
kubectl --kubeconfig=newuser.kubeconfig get pods -n app-prod
```

If the user only has access to the `app-prod namespace`, requests to other namespaces will be denied:

```shell
kubectl --kubeconfig=newuser.kubeconfig get pods -n default
```

Kubernetes will return an access error:

```shell
Error from server (Forbidden): pods is forbidden
```

To check whether a specific action is permitted, use `kubectl auth can-i`:

```shell
kubectl --kubeconfig=newuser.kubeconfig auth can-i update deployments -n app-prod
```

## Revoke Access

How you revoke access depends on what you need to disable.

### Remove Namespace Permissions

To prevent a user from performing actions in a namespace, delete the corresponding `RoleBinding`:

```shell
kubectl delete rolebinding newuser-app-prod-edit -n app-prod
```

If the user was granted cluster-wide access, delete the `ClusterRoleBinding`:

```shell
kubectl delete clusterrolebinding newuser-cluster-admin
```

After the binding is deleted, the token may remain technically valid, but the user will no longer have permission to perform any actions.

### Revoke a Long-Lived Token

If the token was created via a `Secret`, delete that Secret:

```shell
kubectl delete secret newuser-token -n kube-users
```

Once the `Secret` is deleted, the token will no longer authenticate.

### Delete the Account Entirely

To fully remove a user, delete their `ServiceAccount`:

```shell
kubectl delete serviceaccount newuser -n kube-users
```

When a `ServiceAccount` is deleted, all tokens issued for it stop working. Revocation may not be instantaneous, as Kubernetes can cache token validation results for a short period.

After deleting the account, also remove any associated `RoleBindings` and `ClusterRoleBindings` if they are no longer needed.

# S3 Object Storage

Source: https://hostman.com/docs/s3/

The [S3 storage](https://hostman.com/s3-storage/) is a versatile object storage compatible with the Amazon S3 API, capable of storing any type of static data. The data will be stored in one location and a unified format, and you can access it anytime via the API or graphical interface.

Hostman storage offers:

-   **Ease of Use**. You can work with the storage using a variety of tools: API, CLI, Cyberduck, Java SDK, and Python SDK.
    
-   **Triple Data Replication**. Your data is stored in multiple copies to eliminate the risk of loss.
    
-   **Transparent Costs**. You pay only a fixed rate for the selected plan, with no additional charges for traffic.
    

## Storage Usage Examples

-   **Backup Storage**. Save backup copies of your data for unforeseen circumstances. You can set up regular data copies and quickly restore data at any time.
    
-   **Storage of Static and Media Files**. Offload your server drives, leaving only dynamic data that is difficult or impossible to store in the cloud. All static content can be moved to storage, significantly reducing load on your resources.
    
-   **Storage of Archives, Logs, and Records**. Place archives with outdated information, databases, request history, financial reports, and any other data requiring long-term storage but no constant access in the [S3](https://hostman.com/products/s3-storage/) storage.
    
-   **Static Website Hosting**. With the ability to access storage files via HTTP and HTTPS, you can host static websites. This saves server space and reduces infrastructure costs.
    

## Storage Limits

There is only one limitation—on the amount of occupied space, which depends on the selected plan for each bucket. No other parameters (number of buckets, traffic volume, number of requests, etc.) are restricted or billed. You pay only the monthly fixed cost of each bucket according to the chosen plan.

# Manage Storage

Source: https://hostman.com/docs/s3/manage-storage/

Data in [S3 storage](https://hostman.com/s3-storage/) is kept in a unified format: as objects stored in buckets (containers).

-   **Objects** are your files and data in any format. A **bucket** is the storage location for these objects. To place a file in S3 storage, it must be uploaded into a bucket.
    
-   Buckets can be either private or public, with different access methods. Only authorized users (administrators) can access objects in a private container.
    
-   There is a single storage user who has full rights to access all of their buckets. The **Access Key** and **Secret Access Key** are the same across different buckets within one account.

# Create Buckets

Source: https://hostman.com/docs/s3/manage-storage/create-bucket/

To create a new bucket:

1.  Go to the **[S3 Storage](https://hostman.com/s3-storage/)** section and click **Add storage**.
    
2.  Select the required storage size. 
    
3.  Specify the bucket type (you can change this later):
    

-   **Private**: Only the administrator will have access to this bucket and its contents. Choose this type for data that requires restricted access.
    
-   **Public**: Authorization is not required to access data in a public bucket, making it suitable for data accessible to a broad audience.
    

![2c06ca67 778f 49e2 9813 A3fdaeb7ce72](https://content.hostman.com/assets/56a8d076-a44c-4a69-b73a-1289a5838ede.png?width=754&height=696)

4.  In the **Storage Information** section, specify a name for your bucket or keep the suggested default. Bucket names may only contain lowercase Latin letters, numbers, and hyphens.
    

-   If you previously created and deleted a bucket with a specific name, you will not be able to reuse that name. Each bucket name must be unique.
    

6.  Choose the project to which you want to add the bucket.
    
7.  Click **Create**.
    

The bucket will be created instantly and will appear in the dashboard, allowing you to start uploading files to storage.

# Manage Buckets

Source: https://hostman.com/docs/s3/manage-storage/manage-buckets/

## Connecting to a Bucket and Working with Files

The [S3 storage](https://hostman.com/s3-storage/) supports access via the Amazon S3 API and Swift API. You can find the credentials for S3 and Swift in the **Settings** tab in your dashboard.

![E50d9af1 E40d 4dde 83ca 6c5796bcab32](https://content.hostman.com/assets/60d0973f-d771-484a-8fbf-39e38633b039.png?width=1540&height=2028)

You can connect to the storage and manage files (upload, modify, delete) in various ways:

-   You can use an S3 API client. This can be a file manager like Cyberduck or any other tool that supports the S3 protocol, such as S3cmd, Rclone, AWS CLI, S3 Browser, and many more.
    
-   You can implement the connection to the storage in your application’s code using programming language libraries for the S3 protocol.
    
-   You can upload files using the object manager in the dashboard.
    

> [!NOTE]
> The storage supports AWS Signature versions v2 and v4.

To access the files, you can use URLs like: 

```shell
https://s3.hmstorage.net/bucket_name/file_name
```

If the file is located in a directory inside a bucket, the URL will be:

```shell
https://s3.hmstorage.net/bucket_name/directory_name/file_name
```

You can also access files in public buckets using the Virtual-hosted style addressing model, in which case the bucket name is included in the hostname: 

```shell
https://bucket_name.s3.hmstorage.net/file_name
https://bucket_name.s3.hmstorage.net/directory_name/file_name
```

You can also access the bucket through your custom domain by linking it. 

Files in a **public** bucket can be accessed via a browser or another HTTP client by using the file URL.

You can also access files in a **private** bucket through HTTP, but you need to include an additional authentication signature in the request as HTTP headers. For more details, see the description of how to work with [S3](https://hostman.com/products/s3-storage/).

The upload speed for files to or from a bucket is 1 Gbps.

## Changing Storage Size

You can upgrade the bucket plan if you need more storage space. It is not possible to downgrade the plan.

To change the plan: 

1.  Click on the bucket in the dashboard.
    
2.  In the **Settings** tab, click **Change storage size**.
    

![5d5029e7 2e03 4812 9a17 C77d4c1c23d4](https://content.hostman.com/assets/70180069-edde-4551-94db-334c23160789.png?width=1523&height=692)

3.  Select the new plan and save the changes. 
    

The storage space will increase immediately.

## Action History

You can view the actions performed on the bucket in the **History** tab.

![Da1a5cfa Aba2 4042 Aa2d 9181fe92fff2](https://content.hostman.com/assets/7f39635d-22a0-4603-84d3-9874ddffcfc4.png?width=1522&height=697)

The following events are logged:

-   Creating and deleting buckets
-   Changing bucket size
-   Linking domains
-   Issuing SSL certificates
-   Data transfer

## Deleting a Bucket

Deleting a bucket will remove the bucket and all files within it. 

To delete a bucket, click on the three dots next to the bucket in the **S3 Storage** section:

![7e992da0 286d 4fe4 A8e3 299388c0e4d0](https://content.hostman.com/assets/646ba886-b0bb-48f6-b57b-7be3c75bfc1a.png?width=1518&height=684)

Or click the delete icon in the bucket settings:

![849597fb E423 441a 9ac6 E4ca69aeaee6](https://content.hostman.com/assets/52978200-b53b-4e5a-8475-7cacafc619d2.png?width=1535&height=697)

In the popup window, enter the bucket name to confirm deletion.

# Object Manager

Source: https://hostman.com/docs/s3/manage-storage/object-manager/

You can manage files in your bucket directly from the browser using the Object Manager in the control panel, available on your bucket's **Objects** tab.

![2238d90b Fbde 4d18 9e9b B96dc9b88821 06 26 2026 03 37 Pm](https://content.hostman.com/assets/1aa54239-8b2e-4f8c-a77d-1c73055d2789.png?width=1553&height=819)

## Uploading Files

To upload a file to a bucket using the Object Manager:

1.  Go to **S3 Storage** and click the bucket you want to use.
2.  Open the **Objects** tab.
3.  Navigate to the target directory. You can also upload to the bucket root and move the file later.
4.  Click **Upload a file**.
5.  Select a file from your device or drag it into the upload window.

The file will be uploaded to the bucket. Large files are uploaded using [multipart upload](https://hostman.com/docs/s3/supported-features/multipart-upload/) automatically.

## Getting a Link to a File

To copy a link to a file in your bucket:

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Hover over the file row and click the **File link** icon.

The link will be copied to your clipboard.

> [!NOTE]
> If the file is in a private bucket, the link will be valid for 1 hour.

You can also get a link to a [specific version](https://hostman.com/docs/s3/manage-storage/object-manager/#getting-a-link-to-a-previous-version) of a file. 

## Downloading Files

To download a file from a bucket:

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Hover over the file row and click Download.

The file will be saved to your device.

> [!NOTE]
> You can only download individual files. Downloading folders through the Object Manager is not supported. To download entire folders, use a third-party tool such as [Cyberduck](https://hostman.com/docs/s3/tools/cyberduck/) or [S3 Browser](https://hostman.com/docs/s3/tools/s3-browser/).

## Creating Folders

To create a directory inside your bucket:

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory where you want to create the folder. You can also create it in the bucket root and move it later.
4.  Click **Create a folder**.
5.  Enter a name for the folder.
6.  Click the checkmark to save.

## Moving Objects

You can move files and folders between directories within a bucket.

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file or folder.
    -   To move a single object, click the three-dot menu to its right and select **Move**.
    -   To move multiple objects, select them in the list and click **Move** at the bottom of the page.
4.  Navigate to the destination directory.
5.  Click **Move to the current folder**.

## Renaming Objects

To rename a file or folder in your bucket:

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file or folder.
4.  Hover over the object row and click **Rename**.
5.  Enter the new name and click the checkmark to save.

## Editing Metadata

The Object Manager lets you edit both [system and custom metadata](https://hostman.com/docs/s3/supported-features/object-headers/#available-parameters) for files.

> [!NOTE]
> Metadata editing is available for files only, not for directories.

If [versioning](https://hostman.com/docs/s3/supported-features/object-versioning/) is enabled for the bucket, editing metadata creates a new version of the object. The file contents are not changed, and the previous version remains available for restoration.

To edit metadata:

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Click the three-dot menu to the right of the file and select **Edit metadata**.
5.  Set the values you need.
6.  To add custom metadata, click **Add** and fill in the key and value fields.
7.  Save your changes.

## Managing File Versions

If [versioning](https://hostman.com/docs/s3/supported-features/object-versioning/) is enabled for your bucket, the Object Manager lets you view available file versions, as well as download, restore, and delete previous versions.

> [!NOTE]
> Version history is available for files only, not for directories.

### Viewing Version History

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Click the three-dot menu to the right of the file and select **Version history**.

All available versions of the file will be listed.

### Downloading a Previous Version

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Click the three-dot menu and select **Version history**.
5.  Hover over the version you want and click **Download**.

The file will be saved to your device.

### Restoring a Previous Version

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Click the three-dot menu and select **Version history**.
5.  Hover over the version you want and click **Restore**.
6.  Confirm the action.

### Getting a Link to a Previous Version

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Click the three-dot menu and select **Version history**.
5.  Hover over the version you want and click the **File link** icon.

The link will be copied to your clipboard.

### Deleting a Previous Version

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file.
4.  Click the three-dot menu and select **Version history**.
5.  Click the three-dot menu to the right of the version you want to remove and select **Delete**.
6.  Confirm the action.

## Deleting Objects

To delete a file or folder:

1.  Go to **S3 Storage** and click the target bucket.
2.  Open the **Objects** tab.
3.  Navigate to the directory containing the file or folder.
4.  Click the three-dot menu and select **Delete**.
5.  Confirm the deletion.

> [!NOTE]
> Deleting a folder also deletes all of its contents.

# Configure Your Domain

Source: https://hostman.com/docs/s3/manage-storage/link-domain/

You can connect your domain name to a [S3 Storage](https://hostman.com/s3-storage/) bucket. This way, you won’t need to specify the bucket name when accessing the files.

So, instead of these URLs:

```shell
https://s3.hmstorage.net/bucket_name/file_name
https://s3.hmstorage.net/bucket_name/directory_name/file_name
```

you can use URLs like these:

```shell
https://your.domain.tld/file_name
https://your.domain.tld/directory_name/file_name
```

Note that when accessing the domain (`https://your.domain.tld/`), you will not see a file listing or any other index page. The URL must specify the path to a specific file.

> [!NOTE]
> You need to use a third-level domain or higher, such as `hostman.mydomain.com`. 
>
> If your domain uses Cloudflare for proxying, disable it before linking the domain. Wait 5-10 minutes for the changes to take effect, link the domain following the instructions below, and re-enable proxying.

**To configure a domain:**

1.  Create a CNAME for the domain with the value `s3.hmstorage.net`. If the domain uses Hostman name servers, you can do it in the **Domains & SSL** section of your Hostman dashboard.
2.  Wait for 15-20 minutes for the changes to take effect.
3.  Go to the [S3 Storage](https://my.hostman.com/storage) section and click on the bucket.
4.  In the **Domains** tab, click **Link domain**.
5.  Enter your domain name and click **Link domain**.

![Faccb2a9 892b 494d 8b8f A82b87d9ee89](https://content.hostman.com/assets/1e3d1a6c-0b7f-4720-987c-2ac90caf684f.png?width=1530&height=844)

If you leave the **Issue SSL certificate** option checked, we will automatically generate and install a Let's Encrypt SSL certificate on your domain and renew it automatically one week before it expires.

# Data Transfer to S3 Storage

Source: https://hostman.com/docs/s3/manage-storage/data-transfer/

You can transfer data to our storage either automatically using the dashboard's functionality or with third-party tools like Rclone. This article will cover both methods.

## Automatic Data Transfer

You can transfer data from any [S3 compatible storage](https://hostman.com/products/s3-storage/) to Hostman storage through your dashboard. It also allows you to transfer data between buckets within our storage.

**To initiate the transfer:**

1.  Go to the **S3 Storage** section, click on the bucket and open the **Data Transfer** tab.
    
2.  Enter the connection credentials for the third-party storage. You can request this information from your current storage provider.
    
3.  Click **Start Transfer**. Depending on the number of objects in the source bucket, the transfer time may vary. The progress of the copying will be displayed on the bucket page with a yellow indicator.
    

For migrating constantly changing data, we recommend combining this method with the manual synchronization described below.

> [!NOTE]
> Please note that the **Data transfer** option copies data and overwrites existing files. To avoid overwriting, you need to use synchronization.

## Data Migration Using Rclone

This method is preferable for transferring large volumes of data (with millions of objects) and constantly changing data.

You will need:

-   A bucker created in the Hostman S3 storage.
-   A computer or virtual server with Rclone installed.

The process consists of several stages, which we will review in order.

### Step 1. Preparation

Obtain the credentials for the source bucket from the third-party provider and configure Rclone. 

Add two profiles (remotes) to it—one with the credentials from the third-party provider and the other with the credentials for our storage. 

For examples in this article, we will use the profile names `other-provider` and `hostman`.

### Step 2. Initial Data Copy

For large volumes of data, the process can take a significant amount of time, so it's advisable to run the copy command in a `tmux` or `screen` session. This allows you to keep the command running in the background and disconnect from the server.

Start a new `tmux` session with the command:

```shell
tmux new -s storage-migration
```

Start copying objects with the command below, entering your details:

```shell
rclone copy -v -P --log-file=rclone.log --transfers=128 [other-provider]:[bucket-name] hostman:[bucket-name]
```

The `--transfers` option specifies the number of parallel uploads. The more uploads, the faster the copying will occur; however, the maximum number of uploads is limited by the capabilities of the computer running the command. If errors occur, reduce the number.

You can disconnect from the `tmux` session by pressing the key combination Ctrl+B, then releasing the keys and pressing D. You will see the message `[detached (from session storage-migration)]`.

You can reconnect to the active `tmux` session using the command:

```shell
tmux a
```

### Step 3. Data Synchronization

Wait for the copying to complete and then start the synchronization:

```shell
rclone sync -v -P --log-file=rclone.log --transfers=128 [other-provider]:[bucket-name] hostman:[bucket-name]
```

Only changed or new files will be copied to the target bucket.

### Step 4. Stopping the Service and Final Synchronization

To maintain data consistency, you will need to temporarily stop the service. During this time, run the final synchronization:

```shell
rclone sync -v -P --log-file=rclone.log --transfers=128 [other-provider]:[bucket-name] hostman:[bucket-name]
```

This synchronization should be faster than the previous one if not much time has passed and a large amount of new data has not accumulated.

### Step 5. Configure the Service to Work with the New Storage

After the final synchronization of the storages, connect the services to the new storage. Once the services successfully switch to the new storage, you can delete the data from the old storage.

# S3 API Guide

Source: https://hostman.com/docs/s3/manage-storage/s3-guide/

A detailed guide on working with Hostman S3 Storage.

## Connection Credentials

You can find S3 connection details in your Hostman dashboard.

1.  Go to the [**S3 Storage**](https://my.hostman.com/storage) section.
2.  Click on the bucket.
3.  In the **Settings** tab, scroll down to see **S3 Parameters**.

![1cac3c1a 9cb3 4fce B15c Ec12634e9a78](https://content.hostman.com/assets/e2b1589a-f280-43b7-bbc4-cbeb32b8e632.png?width=1540&height=1596)

We support AWS Signature V2 and AWS Signature V4.

To authenticate the requester, all requests must be signed using a signature generated with an Access Key and Secret Key.

## Signature Calculation

Signature calculation consists of three steps:

1.  Obtaining the signing key
2.  Generating the string to sign
3.  Signing the string using the key

#### Obtaining the Signing Key

To get the signing key, encode the following data using the HMAC-SHA256 algorithm:

```shell
DateKey = HMAC-SHA256("AWS4" + "<SecretKey>", "<YYYYMMDD>")
DateRegionKey = HMAC-SHA256(<DateKey>, "<aws-region>")
DateRegionServiceKey = HMAC-SHA256(<DateRegionKey>, "<aws-service>")
SigningKey = HMAC-SHA256(<DateRegionServiceKey>, "aws4_request")
```

We support request signing using the Authorization HTTP header.

Using the Authorization header is the most common method for user authentication.

**General Request Format:**

```shell
Authorization: AWS4-HMAC-SHA256
Credential=12345_USER/20180524/us-2/s3/aws4_request,
SignedHeaders=host;range;x-amz-date,
Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024
```

Where:

-   `AWS4-HMAC-SHA256`: AWS Signature Version 4 (AWS4) and the signature algorithm (HMAC-SHA256)
-   `Credential`: Contains the access key and request information in the format: `${ACCESS_KEY}/${YYYYMMDD}/${REGION}/s3/aws4_request`
-   `SignedHeaders`: Lowercase list of header names used in the signature computation
-   `Signature`: The signed hash, consisting of the request body hash, secret key, and request information (canonical request)

## Generating the String to Sign

To generate the string to sign, create a canonical request in the following format:

```shell
<HTTPMethod>\n
<CanonicalURI>\n
<CanonicalQueryString>\n
<CanonicalHeaders>\n
<SignedHeaders>\n
<HashedPayload>
```

Where:

-   `HTTPMethod`: One of the HTTP methods such as GET, PUT, HEAD, DELETE
-   `CanonicalURI`: URI-encoded path starting after the domain with the first "/", e.g., for `https://s3.hmstorage.net/bucket/sample.txt` it would be `/bucket/sample.txt`
-   `CanonicalQueryString`: Request query parameters
-   `CanonicalHeaders`: List of headers and their values, separated by newline, in lowercase and without spaces
-   `SignedHeaders`: List of header names (no values), sorted alphabetically, in lowercase, separated by semicolons (e.g., `host;x-amz-content-sha256;x-amz-date`)
-   `HashedPayload`: SHA256 hash of the request body: `Hex(SHA256Hash())`. If there's no body, hash an empty string: `Hex(SHA256Hash(""))`.

## Signing the String Using the Key

The string to sign is a concatenation of the following:

```shell
"AWS4-HMAC-SHA256" + "\n" +
timeStampISO8601Format + "\n" +
<Scope> + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))
```

Where:

-   `AWS4-HMAC-SHA256`: Defines the encryption algorithm in use
-   `timeStampISO8601Format`: Current UTC time in ISO 8601 format (e.g., `20130524T000000Z`)
-   `Scope`: Format: `date.Format(<YYYYMMDD>) + "/" + <region> + "/" + <service> + "/aws4_request"`, e.g., `20130606/us-2/s3/aws4_request`. This binds the signature to a specific date, region, and service. When bound to a date, the signature is valid for 15 minutes.

For more details on authentication via the `Authorization` header, refer to the official [Amazon S3 API documentation](https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-auth-using-authorization-header.html).

## Supported S3 Methods

Hostman storage is compatible with AWS S3 methods: Bucket CRUD, Bucket Location, Object CRUD, Object Copy.

Below are the main S3 methods supported by Hostman S3 storage. You can find a complete list of supported features in the [official CEPH documentation](https://docs.ceph.com/en/latest/radosgw/s3/#features-support).

### Bucket Methods

| **Method** | **Description** |
| --- | --- |
| GET Service (List Buckets) | Get a list of buckets |
| GET Bucket (List Objects) | Get list of objects in a bucket |
| GET Bucket Location | Get the bucket's region |
| DELETE Bucket | Delete a bucket |
| HEAD Bucket | Get bucket status |
| PUT Bucket | Create a new bucket |
| GET Bucket ACL | Get access control list (ACL) |
| PUT Bucket ACL | Set ACL |
| GET Bucket Multipart Uploads | Get current multipart uploads |
| PUT Bucket Versioning | Enable or suspend versioning |
| GET Bucket Versioning | Get versioning status (returns nothing if never set) |
| PUT Notification | Enable bucket event notifications |
| DELETE Notification | Delete event notifications |
| GET Notification | Get list of notifications |
| GET Bucket Lifecycle | Get lifecycle configuration |
| DELETE Bucket Lifecycle | Delete lifecycle configuration |
| PUT Bucket Tagging | Add tags to the bucket |
| GET Bucket Tagging | Get bucket tags |
| DELETE Bucket Tagging | Remove bucket tags |
| GET Bucket Policy | Get access policy |
| PUT Bucket Policy | Set access policy |
| DELETE Bucket Policy | Delete access policy |

### Object Methods

| **Method** | **Description** |
| --- | --- |
| PUT Object | Create object |
| PUT Object — Copy | Copy object |
| DELETE Object | Delete object |
| GET Object | Retrieve object |
| HEAD Object | Get object metadata |
| GET Object ACL | Get object ACL |
| PUT Object ACL | Set object ACL |
| POST Multipart Upload | Initiate multipart upload |
| PUT Multipart Upload Part | Upload part of object |
| GET Multipart Upload Parts | Get uploaded parts |
| POST Multipart Upload (Complete) | Complete multipart upload |
| DELETE Multipart Upload | Abort multipart upload |
| PUT Object Tagging | Add tags to object |
| GET Object Tagging | Get object tags |
| DELETE Object Tagging | Remove object tags |

# Tools

Source: https://hostman.com/docs/s3/tools/

There are many tools available that allow for managing data in [S3 object storage](https://hostman.com/s3-storage/).

**Command-line utilities:**

-   [AWS CLI](https://hostman.com/docs/s3/tools/aws-cli/)
-   [S3cmd](https://hostman.com/docs/s3/tools/s3cmd/)

**Desktop applications:**

-   [Cyberduck](https://hostman.com/docs/s3/tools/cyberduck/)
-   [S3 Browser](https://hostman.com/docs/s3/tools/s3-browser/)

**FUSE utilities:**

-   [s3fs](https://hostman.com/docs/s3/tools/s3fs/)
-   [Rclone](https://hostman.com/docs/s3/tools/rclone/)

These tools offer different approaches to managing [S3](https://hostman.com/products/s3-storage/), allowing you to choose the most convenient option for your tasks.

# AWS CLI

Source: https://hostman.com/docs/s3/tools/aws-cli/

AWS CLI is a command-line interface for working with Amazon services. It provides a set of commands for managing files in cloud storage.

## Installation

To install AWS CLI on Ubuntu, use the command:

```shell
sudo apt install awscli -y
```

After installation, you can check the AWS version with the command:

```shell
aws --version
```

You can find information on installing AWS CLI on other operating systems in the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html).

## Configuration

To configure AWS to work with our [S3 object storage](https://hostman.com/s3-storage/), use the command:

```shell
aws configure
```

An interactive prompt will appear, asking for connection credentials. Enter them as follows, using the values from your bucket settings in your dashboard:

```shell
AWS Access Key ID [None]: <Access Key>
AWS Secret Access Key [None]: <Secret Access Key>
Default region name [None]: us-2
Default output format [None]: json
```

This will create a hidden `.aws` directory with config and credentials files, which contain AWS settings and authorization keys, respectively.

## Working with Files

### Retrieving a List of Files in a Bucket

To retrieve a list of files, use the `ls` command:

```shell
aws s3 ls s3://<bucket-name> --endpoint-url https://s3.hmstorage.net
```

### Uploading a Local File to the Bucket

To upload files, use the `cp` command. In the example below, the `test.txt` file is uploaded:

```shell
aws s3 cp test.txt s3://<bucket-name> --endpoint-url https://s3.hmstorage.net
```

### Deleting a File in the Bucket

To delete a file, use the `rm` command. In the example below, we delete `test.txt`:

```shell
aws s3 rm s3://<bucket-name>/test.txt --endpoint-url https://s3.hmstorage.net
```

### Synchronizing Files

To sync files between a local directory (in this example, the current directory `.`) and the bucket, use the `sync` command:

```shell
aws s3 sync . s3://<bucket-name> --endpoint-url https://s3.hmstorage.net
```

You can find detailed information on these and other commands in the [AWS documentation](https://docs.aws.amazon.com/cli/latest/reference/s3/).

## Multipart Upload

To perform a multipart upload using the AWS CLI, you need to use the `aws s3api` command. This process involves creating and completing a multipart upload in a few steps.

### Preparation

Before performing a multipart upload, the file must be split into parts. You can use the `split` utility to divide the file:

```shell
split -b <part_size> <path_to_file> <part_name_prefix>
```

-   `<part_size>`: The size of each part (e.g., for 5 MB, use `5M`).
    
-   `<path_to_file>`: Path to the source file.
    
-   `<part_name_prefix>`: Prefix for part names. For example, if you specify `part`, the parts will be named `partaa`, `partab`, and so on.
    

### Step 1. Initialize the Upload

Start the multipart upload to get an `UploadId`, which is needed for subsequent steps:

```shell
aws s3api create-multipart-upload --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net --key <file_name_in_bucket>
```

The command's output will include an `UploadId`. Save it, as it will be used for uploading parts and completing the process.

### Step 2. Upload Parts

Use the `upload-part` command to upload each file part. You need to specify the `UploadId`, `PartNumber`, and the file part path. For example, to upload the first part:

```shell
aws s3api upload-part --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net --key <file_name_in_bucket> --part-number 1 --body <path_to_part> --upload-id <UploadId>
```

Repeat this command for each part of the file, incrementing the `--part-number` and updating `--body` with the appropriate file part.

### Step 3. Complete the Upload

After all parts are uploaded, use the `complete-multipart-upload` command. First, create a `JSON` file with details about the uploaded parts, including the `ETag` and `PartNumber`:

```shell
{
  "Parts": [
    {
      "ETag": "<ETag_of_part_1>",
      "PartNumber": 1
    },
    {
      "ETag": "<ETag_of_part_2>",
      "PartNumber": 2
    }
  ]
}
```

Then, complete the upload:

```shell
aws s3api complete-multipart-upload --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net --key <file_name_in_bucket> --upload-id <UploadId> --multipart-upload file://<path_to_JSON_file>
```

### Abort the Upload

If you want to cancel the upload, use the following command:

```shell
aws s3api abort-multipart-upload --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net --key <file_name_in_bucket> --upload-id <UploadId>
```

### List Multipart Upload Parts

To check the parts uploaded so far, use the `list-parts` command:

```shell
aws s3api list-parts --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net --key <file_name_in_bucket> --upload-id <UploadId>
```

## Presigned URLs

Presigned URLs allow you to create temporary links for accessing private objects in [S3](https://hostman.com/products/s3-storage/). These links provide access to an object without requiring authentication, and unlike changing an object's ACL, presigned URLs always have an expiration time (maximum 7 days).

### Generating a Presigned URL

Use the `presign` command to generate a temporary link:

```shell
aws s3 presign s3://<bucket_name>/<file_path> --endpoint-url https://s3.hmstorage.net
```

To set a custom expiration time, use the `--expires-in` flag, which specifies the time in seconds (default is 3600 seconds):

```shell
aws s3 presign s3://<bucket_name>/<file_path> --expires-in <time_in_seconds> --endpoint-url https://s3.hmstorage.net
```

### How Presigned URLs Work

Presigned URLs use AWS’s standard authorization mechanism. The difference is that the authorization values, typically sent as headers, are appended to the URL as query parameters. This allows external users to access the link via a browser or other client without additional setup. For example, a generated link might look like this:

```shell
https://s3.hmstorage.net/841b4a72-presigned/README.md?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=4AP1MJKIJFLUJN9ABQZ1%2F20241113%2Fus-2%2Fs3%2Faws4_request&X-Amz-Date=20241113T104406Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=737a677e78f88ab989b1c9b8edb454f70ea8da42e6b79774e68aa0fc6a52cb81
```

# Cyberduck

Source: https://hostman.com/docs/s3/tools/cyberduck/

Cyberduck is a file manager that supports FTP, SFTP, OpenStack Swift, and Amazon S3 protocols, making it convenient for working with cloud storage. In our Cyberduck profile, the OpenStack Swift protocol is used.

## Installing Cyberduck on Windows

1.  Download Cyberduck from the [official website](https://cyberduck.io/download/) and install it.
    
2.  In your bucket settings, download the Hostman profile file.
    

![817ac175 Dffa 4305 8899 29090796e90c](https://content.hostman.com/assets/b53e287f-5fa1-4f6e-945a-27cff90dfb21.png?width=1518&height=734)

3.  Place the profile in the `profiles` directory (typically located at `C:\Program Files\Cyberduck\profiles`).
    
4.  Launch Cyberduck and click on **Open Connection**.
    

![Cyberduck E Hsbuw Wdzr](https://content.hostman.com/assets/631f5b10-a761-4d27-8936-d67893be15b0.png?width=552&height=562)

_The "Open Connection" window in the [Cyberduck](https://cyberduck.io/) interface_

5.  Select the **Hostman [S3 Storage](https://hostman.com/s3-storage/)** profile.
    
6.  Enter the connection credentials.
    
    -   AccountID: enter `your_hostman_login:swift`
        
    -   Password: enter the password from the **Cyberduck** tab.
        

![D86ae21e 1d8d 4072 9ac4 2cc8995c3979](https://content.hostman.com/assets/a43260b1-6b95-4ab5-ba42-b276f826eee3.png?width=1518&height=734)

7.  Click **Connect**.
    

Once connected, you will see a list of the created buckets.

#### Console Version

Cyberduck also offers a console version for Windows. You can install it using the Chocolatey package manager:

```shell
choco install duck
```

Next download the Hostman profile file from the bucket settings in the dashboard and place it in the `C:\Program Files\Cyberduck\profiles` directory.

![817ac175 Dffa 4305 8899 29090796e90c](https://content.hostman.com/assets/b53e287f-5fa1-4f6e-945a-27cff90dfb21.png?width=1518&height=734)

## Installing Cyberduck on MacOS

1.  Download Cyberduck for free from the [official website](https://cyberduck.io/download/) or purchase it through the App Store.
2.  In your bucket settings, download the Hostman profile file.

![817ac175 Dffa 4305 8899 29090796e90c](https://content.hostman.com/assets/b53e287f-5fa1-4f6e-945a-27cff90dfb21.png?width=1518&height=734)

3.  Place the profile in the profiles directory:

```shell
~/Library/Group Containers/G69SCX94XU.duck/Library/Application Support/duck/Profiles
```

4.  Launch Cyberduck and select the **Hostman [S3](https://hostman.com/products/s3-storage/) Storage** profile.
5.  Enter the connection credentials.

-   -   AccountID: enter `your_hostman_login:swift`
    -   Password: enter the password from the **Cyberduck** tab.

![D86ae21e 1d8d 4072 9ac4 2cc8995c3979](https://content.hostman.com/assets/a43260b1-6b95-4ab5-ba42-b276f826eee3.png?width=1518&height=734)

6.  Click **Connect**.

Once connected, you will see a list of the created buckets.

#### Console Version

You can also use the console version of Cyberduck. You can install it using Homebrew.

1.  Run the following command to download the latest installer version:

```shell
brew install duck
```

2.  Download the Hostman profile file and add it to Cyberduck.

![817ac175 Dffa 4305 8899 29090796e90c](https://content.hostman.com/assets/b53e287f-5fa1-4f6e-945a-27cff90dfb21.png?width=1518&height=734)

## Installing Cyberduck on Linux

For Linux, you can use a console version of Cyberduck.

1.  Add the duck repository:

```shell
echo -e "deb https://s3.amazonaws.com/repo.deb.cyberduck.io stable main" | sudo tee /etc/apt/sources.list.d/cyberduck.list > /dev/null
```

2.  Download the public GPG key from `keyserver.ubuntu.com`:

```shell
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys FE7097963FEFBE72
```

3.  Update the repository:

```shell
sudo apt-get update
```

4.  Install the Cyberduck CLI:

```shell
sudo apt-get install duck
```

5.  Create a directory for profiles:

```shell
mkdir -p ~/.duck/profiles
```

6.  Download the Hostman profile:

```shell
wget -O ~/.duck/profiles/hostman.cyberduckprofile https://st.hostman.com/cloud-static/hostman/hostman.cyberduckprofile
```

## Commands for Managing Storage

The commands follow this format:

```shell
duck <generic_option> <argument> hostman:/<bucket_name> --username <login>:swift --password <password>
```

Where:

-   `<generic_option>` — an additional [option](https://docs.cyberduck.io/cli/#generic-options), such as `--verbose` or `--retry`.
-   `<argument>` — a `duck` utility argument. You can get the full list of arguments and options by running `duck --help`.
-   `<bucket_name>` — the name of the bucket.
-   `<login>` — your Hostman account login. In the `--username` parameter, you should always enter the login and `swift` separated by a colon, e.g., `xg60398:swift`.
-   `<password>` — the storage password which you can copy from the **Cyberduck** tab.

![D86ae21e 1d8d 4072 9ac4 2cc8995c3979](https://content.hostman.com/assets/a43260b1-6b95-4ab5-ba42-b276f826eee3.png?width=1518&height=734)

Example:

```shell
duck --list hostman:/7ebe7c09-90e3e6df-c3e1-4bd2-bb6f-166b49bb32f8 --username xg60398:swift --password gUAD0KCFhsGfbV2Arfhe9y5CAA4i8tLBqNyzAUW8
```

### Listing Files

To get a list of files in a bucket, use either the `--list` or `-l` argument:

```shell
duck --list hostman:/<bucket_name> --username <login>:swift --password <password>
```

### Downloading Files

To download a file to your local device, use the `-d` argument:

```shell
duck -d hostman:/<bucket_name> --username <login>:swift --password <password>
```

### Editing Files

Use the `--edit` argument to open a file for editing, make changes, and save the updated version back to the bucket:

```shell
duck --edit hostman:/<bucket_name> --username <login>:swift --password <password>
```

### Uploading a File to a Bucket

To upload a file to storage, use `--upload`:

```shell
duck --upload hostman:/<bucket_name> <local_file_name> --username <login>:swift --password <password>
```

### Copying Files

To copy a file from one bucket to another, use `--copy`, specifying first the current file location and then its new location in the target bucket:

```shell
duck --copy hostman:/<current_bucket_name>/<file_path> hostman:/<new_bucket_name>/<file_path> --username <login>:swift --password <password>
```

### Backing Up Files

To regularly back up files from a specific directory to storage, you can create a Cron job using the following script:

```bash
#!/bin/bash
USERNAME=<login>
PASSWORD=<password>
BACKUP_PATH=<bucket_name>/<directory_path>
LOCAL_PATH=<local_directory_path>
duck --upload "hostman:/${BACKUP_PATH}" "${LOCAL_PATH}" --existing rename --username "${USERNAME}:swift" --password "${PASSWORD}" -q -y
```

The `--existing` argument specifies what to do with existing files. The example above uses the `rename` option, which renames an existing copy by adding the time and date. Other options include:

-   `overwrite` to replace the existing file with the new version.
-   `skip` to upload only new files added after the last upload, skipping even modified duplicates.
-   `compare` for differential backup, which replaces the old version with the new if they differ in size, modification date, or checksum.

Example:

```shell
duck --upload hostman:/<bucket_name>/<directory_path> <local_directory_path> --existing compare --username <login>:swift --password <password>
```

For information on all available options, use:

```shell
duck --help
```

### File Synchronization

The `--synchronize` option lets you sync the content of a local directory with one in storage. Any changes, additions, or deletions made locally will be mirrored in storage, and vice versa, resulting in both directories having an identical file set in the same version.

Example:

```shell
duck --synchronize hostman:/<bucket_name>/<directory_path> <local_directory_path> --username <login>:swift --password <password>
```

To automatically perform synchronization and keep the file copies in storage up to date, you can create a Cron job with the following script:

```bash
#!/bin/bash
USERNAME=<login>
PASSWORD=<password>
BACKUP_PATH=<bucket_name>/<directory_path>
LOCAL_PATH=<local_directory_path>
duck --synchronize "hostman:/${BACKUP_PATH}" "${LOCAL_PATH}" --username "${USERNAME}:swift" --password "${PASSWORD}" -q -y
```

# Rclone

Source: https://hostman.com/docs/s3/tools/rclone/

Rclone is a command-line utility for synchronizing files and directories between a local machine and cloud storage.

## Installing Rclone

You can download Rclone from the [official website](https://rclone.org/downloads/) and follow the [installation guides](https://rclone.org/install/), also available on the official site. 

For Windows, simply download and run `rclone.exe` via the command line.

## Configuring Rclone

To set up Rclone to work with our [S3 object storage](https://hostman.com/s3-storage/):

1.  Create the `rclone.conf` file in the `.config/rclone` directory in the root of your home directory
2.  Add the following content:

```shell
[hostman]
type = s3
provider = Other
env_auth = false
access_key_id = <Access_Key>
secret_access_key = <Secret_Access_Key>
endpoint = https://s3.hmstorage.net
```

Alternatively, you can use the configuration wizard, which will create a similar file. To launch the configuration wizard, run the command:

```shell
rclone config
```

Below is an example of setting up using the configuration wizard.

-   **No remotes found - make a new one**

Enter `n` and then the name `hostman`.

```shell
No remotes found - make a new one
n) New remote
s) Set configuration password
q) Quit config
n/s/q> n
name> hostman
```

-   **Option Storage**

Select `Amazon S3 Compliant Storage Providers`.

```shell
Storage> 4
```

-   **Option provider**

Select `Any other S3 compatible provider`.

```shell
provider> 32
```

-   **Option env\_auth**

Enter `false`.

```shell
env_auth> false
```

-   **Option access\_key\_id**

Enter the `Access Key` from your bucket settings. For example:

```shell
access_key_id> 6RNN1MM9UZOUU5XWVQUE
```

-   **Option secret\_access\_key**

Enter the `Secret Access Key` from your bucket settings. For example:

```shell
secret_access_key> jX8DgkESG2uqTtQYAuT25FZhctrbz2mhyBrwUgKK
```

-   **Option region**

Enter `us-2`.

```shell
region> us-2
```

-   **Option endpoint**

Enter `https://s3.hmstorage.net`

```shell
endpoint> https://s3.hmstorage.net
```

-   **Option location\_constraint**

Leave blank and press Enter.

```shell
location_constraint>
```

-   **Option acl**

Leave blank and press Enter.

```shell
acl>
```

-   **Edit advanced config?**

Enter `n`.

```
y/n> n
```

-   **Configuration complete**

Check the details and press `y`.

```shell
Options:
- type: s3
- provider: Other
- access_key_id: 6RNN1MM9UZOUU5XWVQUE
- secret_access_key: jX8DgkESG2uqTtQYAuT25FZhctrbz2mhyBrwUgKK
- region: us-2
- endpoint: https://s3.hmstorage.net

Keep this "hostman" remote?
y) Yes this is OK (default)
e) Edit this remote
d) Delete this remote
y/e/d> y
```

-   **Current remotes**

Enter `q` to exit.

```shell
Current remotes
Name                 Type
====                 ====
hostman2             s3

e) Edit existing remote
n) New remote
d) Delete remote
r) Rename remote
c) Copy remote
s) Set configuration password
q) Quit config
e/n/d/r/c/s/q> q
```

## Usage Examples

For a complete list of supported commands, refer to the [Rclone documentation](https://rclone.org/commands/). 

The storage name specified in the `rclone.conf` configuration file should be used as the host name. In our example earlier, we configured a storage named hostman.

### Viewing the List of Buckets

```shell
rclone lsd <host_name>:
```

For example:

```shell
rclone lsd hostman:
```

```shell
       -1 2021-12-10 11:34:51     -1 1d65c254-17ab-4b22-b262-1111fc006937
       -1 2022-01-13 10:05:47     -1 3b24945b-d373-4713-89ec-3dece346c7b3
       -1 2022-01-14 12:31:36     -1 bbf30ad7-8872-40fc-8d41-54537d894b7f
```

### Getting a List of Files in a Bucket

```shell
rclone ls <host_name>:<bucket_name>
```

For example:

```shell
rclone ls hostman:3b24945b-d373-4713-89ec-3dece346c7b3
```

```shell
    13 test.txt
    13 test1.txt
```

### Uploading a File to a Bucket

```shell
rclone -P copy <file_name> <host_name>:<bucket_name>
```

For example:

```shell
rclone -P copy test5.txt hostman:3b24945b-d373-4713-89ec-3dece346c7b3
```

### Deleting a File in a Bucket

```shell
rclone delete <host_name>:<bucket_name>/<file_name>
```

For example:

```shell
rclone delete hostman:3b24945b-d373-4713-89ec-3dece346c7b3/test5.txt
```

### Copying Files between Buckets

```shell
rclone copyto -vP --log-file=rclone_<source_bucket_name>.log --transfers=256 <source_host_name>:<source_bucket_name> <destination_host_name>:<destination_bucket_name>
```

### Synchronizing Files Between a Bucket and a Local Directory

```shell
rclone -P sync <host_name>:<bucket_name> /path/to/directory
```

For example:

```shell
rclone -P sync hostman:3b24945b-d373-4713-89ec-3dece346c7b3 /root/test
```

For reverse synchronization, simply reverse the arguments.

# S3cmd

Source: https://hostman.com/docs/s3/tools/s3cmd/

S3cmd is an S3 API client with a command-line interface, used to interact with [S3-compatible storage](https://hostman.com/products/s3-storage/).

## Installation

To install S3cmd, use the following commands.

-   Ubuntu:

```shell
sudo apt install s3cmd -y
```

-   CentOS:

```shell
sudo dnf install s3cmd -y
```

-   Arch Linux:

```shell
sudo pacman -S s3cmd
```

-   MacOS (using [Homebrew](https://brew.sh/)):

```shell
brew install s3cmd
```

-   Windows (using [Chocolatey](https://chocolatey.org/install)):

```shell
choco install s3cmd -y
```

Make sure to run PowerShell as an administrator.

## Configuration

To configure S3cmd to work with our [S3 object storage](https://hostman.com/products/s3-storage/), you need to create a `.s3cfg` file in your home directory with the following contents:

```shell
[default]
access_key = <Access Key>
secret_key = <Secret Access Key>
bucket_location = us-2
host_base = s3.hmstorage.net
host_bucket = s3.hmstorage.net
use_https = True
```

You can find **Access Key** and **Secret Access Key** in the bucket **Settings** under **S3 parameters**.

![1cac3c1a 9cb3 4fce B15c Ec12634e9a78](https://content.hostman.com/assets/e2b1589a-f280-43b7-bbc4-cbeb32b8e632.png?width=1540&height=1596)

## Usage Examples

### Listing Files in a Bucket

To list the files in a bucket, use the `ls` command:

```shell
s3cmd ls s3://<bucket_name>
```

### Uploading a Local File to a Bucket

To upload files, use the `put` command. In the example below, the file `text.txt` is uploaded:

```shell
s3cmd put test.txt s3://<bucket_name>
```

### Multipart Upload

The S3cmd client supports multipart upload, which is automatically enabled for files larger than 15 MB. This method splits the file into multiple parts (chunks) and uploads them in parallel, speeding up large file transfers and improving fault tolerance.

If needed, multipart upload can be disabled using the `--disable-multipart` option.

To change the size of individual chunks, use the `--multipart-chunk-size-mb=SIZE` option, where `SIZE` is the size of each chunk in megabytes. By default, the chunk size is 15 MB, with a minimum allowable size of 5 MB and a maximum of 5 GB.

For example, to set the chunk size to 10 MB, use the following command:

```shell
s3cmd put <file_name> --multipart-chunk-size-mb=10 s3://<bucket_name>
```

This setting allows you to optimize large file uploads based on network bandwidth and performance requirements.

### Managing Interrupted Multipart Uploads

If a multipart upload is interrupted, file fragments do not appear in the bucket but still occupy disk space on the server. To view a list of interrupted uploads and see which fragments are using space, use the following command:

```shell
s3cmd multipart s3://<bucket_name>
```

This command shows the date and time the upload started, the file path, and a unique upload identifier (ID).

To delete fragments from failed uploads, use this command:

```shell
s3cmd abortmp s3://<bucket_name>/<file_name> <upload_ID>
```

### Downloading a File from a Bucket

To download a file from a bucket to your local device, use `get`:

```shell
s3cmd get s3://<bucket_name>/test.txt
```

### Deleting a File in a Bucket

To delete a file, use the `del` command. In the example below, we delete the file `text.txt`:

```shell
s3cmd del s3://<bucket_name>/test.txt
```

### File Synchronization

To synchronize files between a local directory (in this example, the current directory: `.`) and a bucket, use `sync`:

```shell
s3cmd sync . s3://<bucket_name>
```

For a full list of commands and additional information, consult the [S3cmd documentation](https://s3tools.org/usage).

# s3fs

Source: https://hostman.com/docs/s3/tools/s3fs/

s3fs is a utility for Linux and macOS that allows you to mount cloud storage buckets via FUSE.

## Installation

To install s3fs on Ubuntu, use the following command:

```shell
sudo apt install s3fs
```

It is recommended to use s3fs version 1.90 or higher. 

To install the latest version of s3fs on Ubuntu, you can build it from source using these commands:

```shell
sudo apt install build-essential automake libcurl4-openssl-dev libxml2-dev pkg-config libssl-dev libfuse-dev git
git clone https://github.com/s3fs-fuse/s3fs-fuse.git
cd s3fs-fuse
./autogen.sh
./configure
make
sudo make install
```

For additional information and installation instructions on other operating systems, refer to the [s3fs documentation](https://github.com/s3fs-fuse/s3fs-fuse#installation).

## Configuration

To configure s3fs for use with the [S3-compatible object storage](https://hostman.com/products/s3-storage/), save the access key and secret key in the `~/.passwd-s3fs` file using the following command:

```shell
echo <Access Key>:<Secret Access Key> > ~/.passwd-s3fs
```

You can find the Access Key and Secret Access Key in your bucket settings under the **S3 parameters** section.

![1cac3c1a 9cb3 4fce B15c Ec12634e9a78](https://content.hostman.com/assets/e2b1589a-f280-43b7-bbc4-cbeb32b8e632.png?width=1540&height=1596)

Restrict access to the `~/.passwd-s3fs` file:

```shell
chmod 600 ~/.passwd-s3fs
```

## Mounting a Bucket

To mount a bucket, choose a mount directory (in this example, `/mnt/s3/`) and execute the following command, specifying the correct bucket name and directory path:

```shell
s3fs <bucket_name> /mnt/s3/ -o use_path_request_style -o url=https://s3.hmstorage.net -o passwd_file=~/.passwd-s3fs
```

## Automatic Mounting at System Startup

To automatically mount the bucket at system startup, add the following line to the /etc/fstab file:

```shell
s3fs#<bucket_name> /mnt/s3 fuse _netdev,allow_other,use_path_request_style,url=https://s3.hmstorage.net,passwd_file=/root/.passwd-s3fs 0 0
```

For additional information on using s3fs, details on all parameters, and troubleshooting tips, consult the project's [documentation](https://github.com/s3fs-fuse/s3fs-fuse/wiki/Fuse-Over-Amazon), including the [FAQ](https://github.com/s3fs-fuse/s3fs-fuse/wiki/FAQ) section.

# S3 Browser

Source: https://hostman.com/docs/s3/tools/s3-browser/

S3 Browser is a graphical interface for managing S3-compatible storage on Windows, similar in functionality to FTP clients.

You can download the latest version of S3 Browser from the [developer's website](https://s3browser.com).

## Configuration

To connect to the storage, you will need the **S3 Parameters** available in the bucket **Settings**:

![Image6](https://content.hostman.com/assets/ccda87b0-981b-41db-a72f-dd8785e459e0.png?width=1533&height=1233)

1.  Open the connection setup wizard by going to **Accounts** > **Add new account**.
    
2.  Fill in the connection details:
    

-   **Display name**: The name for this connection account (you can set any name you prefer).
    
-   **Account type**: Select `[S3 Compatible Storage](https://hostman.com/products/s3-storage/)`.
    
-   **REST Endpoint**: `s3.hmstorage.net`
    
-   **Access Key ID**: `<Your Access Key>`
    
-   **Secret Access Key**: `<Your Secret Access Key>`
    

3.  Click on **advanced settings** at the bottom left.
    
4.  Make sure to select `AWS Signature V4` or `V2` versions and `Path style`.
    

![Image4](https://content.hostman.com/assets/56667119-5959-4a59-a845-b1b2fdec3245.png?width=662&height=690)

_Configuring storage settings in the [S3 Browser](https://s3browser.com/) interface_

5.  Click **Close**, then complete the account setup by clicking **Add new account**.
    

Once connected, you will see all existing buckets created on your Hostman account.

## Usage Examples

Let’s go over basic operations for working with the storage via S3 Browser. 

### Creating a New Bucket

To create a new bucket:

1.  Click on **New bucket**. 
2.  Enter the bucket name.
3.  Click **Create new bucket**.

![Image1](https://content.hostman.com/assets/89344ce2-96ca-464b-9a27-c90601c635da.png?width=1401&height=879)

_Creating a new bucket in the [S3 Browser](https://s3browser.com/) interface_

### Uploading Objects

To upload files or directories:

1.  Click **Upload**.
2.  Select **Upload file(s)** or **Upload folder(s)**.
3.  Select files or directories from your computer.

You can also upload files using drag&drop.

![Image9](https://content.hostman.com/assets/3075c2cb-7505-4260-a064-2d4c2243d49e.png?width=1405&height=880)

_Uploading an object in the [S3 Browser](https://s3browser.com/) interface_

### Downloading Objects

To download files or directories in S3 Browser:

1.  Select the file or directory and click the **Download** button.
2.  Choose the folder where you want to save the downloaded file or directory.
3.  The download will start automatically.

Note that large files are downloaded in parts and, upon completion, the file is reassembled on your device from the downloaded fragments.

![Image3](https://content.hostman.com/assets/4da0fa55-8405-4748-bea8-e03f6f3729ba.png?width=1399&height=878)

_Downloading objects in the [S3 Browser](https://s3browser.com/) interface_

### Deleting Objects

To delete files or directories:

1.  Select the file or directory.
2.  Click **Delete**. 
3.  Confirm deletion.

![Image5](https://content.hostman.com/assets/260b887a-f97d-4815-938e-ef8c99977b54.png?width=1402&height=878)

_Deleting objects in the [S3 Browser](https://s3browser.com/) interface_

### Managing Interrupted Multipart Uploads

[S3](https://hostman.com/products/s3-storage/) supports multipart uploads, which split a file into multiple parts (chunks) and upload them in parallel, speeding up large file transfers and improving fault tolerance.

If a multipart upload is interrupted, file fragments won’t appear in the bucket but will still occupy disk space on the server. To view incomplete uploads, go to **Tools** → **Uncompleted Multipart Uploads**.

![Image7](https://content.hostman.com/assets/b8611183-830f-4141-9321-6ef0f212eaa1.png?width=1400&height=878)

_Tools menu in the [S3 Browser](https://s3browser.com/) interface_

Here you can see all the unfinished uploads. To delete, select an upload and click **Abort Selected**.

![Image8](https://content.hostman.com/assets/09a18819-de03-4afb-9d1d-cb8a65d2c1b7.png?width=1398&height=878)

_Uncompleted Multipart Uploads window in the [S3 Browser](https://s3browser.com/) interface_

The upload will no longer take space in the bucket.

# S3 Storage Use Cases

Source: https://hostman.com/docs/s3/use-cases/

-   [Backing Up to S3 with Duplicity](https://hostman.com/docs/s3/use-cases/duplicity-backups/)
-   [Connecting S3 Storage to Nextcloud](https://hostman.com/docs/s3/use-cases/nextcloud/)

# Backing Up to S3 with Duplicity

Source: https://hostman.com/docs/s3/use-cases/duplicity-backups/

Duplicity is a command-line utility for backup and recovery. Backups can be uploaded to storage using protocols such as SCP, SFTP, WebDAV, [S3](https://hostman.com/products/s3-storage/), Swift, and others. By default, the utility encrypts backups using GnuPG.

Below is an example of setting up Duplicity for backing up data to Hostman object storage using the Swift protocol.

1.  Create a separate bucket for backups.
    
2.  Install the duplicity package on the server along with the required dependencies.
    
    -   For Duplicity versions below 0.8.x (which use Python 2), you need the `python-swiftclient` package.
        
    -   For Duplicity version 0.8.x and above, install `python3-swiftclient`.
        

Use the following commands:

```shell
sudo apt-get install duplicity
```

3.  Create a file named `backup.sh` with the following content, replacing the variable values with your actual credentials. You can find them in the **Swift parameters** section in your bucket **Settings**.
    

```bash
#!/usr/bin/env bash

export SWIFT_PASSWORD="storage_password"
export SWIFT_AUTHVERSION=2
export SWIFT_TENANTNAME="account_login"
export SWIFT_USERNAME="account_login"
export SWIFT_AUTHURL="URL"
export PASSPHRASE="encryption_password"

source=/home  # Path to the directory to be backed up
dest=bucket_name  # Destination bucket for backups

duplicity "$source" swift://"$dest"
```

4.  Run the following command to make the script executable:
    

```shell
chmod +x backup.sh
```

5.  Execute the script with the following command:
    

```shell
./backup.sh
```

# Connecting S3 Storage to Nextcloud

Source: https://hostman.com/docs/s3/use-cases/nextcloud/

Using [S3 storage](https://hostman.com/products/s3-storage/) in Nextcloud as external storage allows you to store files in the cloud and access them quickly. This integration reduces the risk of data loss and decreases the load on your local server. 

This guide explains how to set up an S3 storage connection in Nextcloud.

1.  Log in to Nextcloud as an administrator.
    
2.  Enable external storage support:
    

-   Navigate to the **Apps** section, then to the **Your Apps** tab.
    
-   Find the extension **External storage support** in the list and enable it by clicking the **Enable** button.
    

4.  Configure the S3 connection:
    

-   Go to **Server Settings** and select the **External Storage** tab.
    
-   In the **Add Storage** column, choose **Amazon S3**. In the **Authentication** field, select **Access Key**.
    

6.  Fill out the configuration settings:
    

-   **Cluster**: `s3.hmstorage.net`
    
-   **Folder Name**: Specify the name that will appear in the Nextcloud file manager.
    
-   **Bucket**: Enter the name of your S3 bucket.
    
-   **Host Name**: `s3.hmstorage.net`
    
-   **Port**: Leave this field empty.
    
-   **Region**: `us-2`
    
-   **Access Key**: `<your Access Key>`
    
-   **Secret Key**: `<your Secret Access Key>`
    

![1cac3c1a 9cb3 4fce B15c Ec12634e9a78](https://content.hostman.com/assets/e2b1589a-f280-43b7-bbc4-cbeb32b8e632.png?width=1540&height=1596)

-   **Use SSL**: Ensure the checkbox is ticked.
    
-   Leave other parameters at their default values.
    

5.  Set user access:
    

-   In the **Available For** column, choose the desired users or groups, or select **All Users**.
    
-   Save the changes by clicking the **Save** button.
    

To verify the setup, upload any file to the connected folder in Nextcloud. Then, check that the file appears in the bucket's **Objects** section in the Hostman dashboard.

# Supported Features

Source: https://hostman.com/docs/s3/supported-features/

-   [Confuguring CORS](https://hostman.com/docs/s3/supported-features/cors/)
-   [Managing Object Lifecycle](https://hostman.com/docs/s3/supported-features/object-lifecycle/)
-   [Object Versioning](https://hostman.com/docs/s3/supported-features/object-versioning/)
-   [Object Lock](https://hostman.com/docs/s3/supported-features/object-lock/)
-   [Setting Object Headers](https://hostman.com/docs/s3/supported-features/object-headers/)
-   [Configuring Bucket Policies](https://hostman.com/docs/s3/supported-features/bucket-policies/)
-   [Multipart Upload](https://hostman.com/docs/s3/supported-features/multipart-upload/)
-   [Configuring S3 Proxying via Nginx](https://hostman.com/docs/s3/supported-features/configuring-s3-proxying-via-nginx/)
-   [Presigned URL](https://hostman.com/docs/s3/supported-features/presigned-url/)
-   [Static Websites](https://hostman.com/docs/s3/supported-features/static-websites/)

# Configure CORS

Source: https://hostman.com/docs/s3/supported-features/cors/

When using files from [S3](https://hostman.com/products/s3-storage/) buckets on external resources, such as a website, you might encounter a CORS (Cross-Origin Resource Sharing) error. This error occurs when the browser blocks cross-origin requests to your bucket’s resources. 

To resolve this issue, you need to configure specific CORS rules for the bucket to allow cross-origin requests. You can set up CORS in the Hostman dashboard or via AWS CLI.

## In the Hostman Dashboard

1.  Go to the **S3 storage** section and click on the bucket.
2.  In the **Settings** tab, click **Change** next to the **CORS** parameter.

![Ef1c7645 66e7 4d0f B2e7 98acbf2ef091](https://content.hostman.com/assets/3d436263-9752-4510-b299-1e332dd6429a.png?width=1535&height=868)

3.  Fill in the required CORS rule parameters:
    

-   -   **Allowed Origins** – Specifies the origins from which requests to the bucket are allowed. Example: `https://example.com`. You can use `*` to allow requests from all domains.
    -   **Allowed Methods** – Defines the HTTP methods that are permitted for CORS requests.
    -   **Allowed Headers** – Specifies the headers allowed in requests. Example: `Authorization`, `Content-Type`. You can specify `*` to allow all headers.
    -   **Expose Headers** – A list of headers that will be accessible to the client in the response. By default, access to some headers is blocked by the browser. Example: `ETag`, `x-amz-meta-custom-header`.
    -   **Max Age Seconds** – Defines the time in seconds for which CORS request results can be cached on the client side. Example: `3600` (1 hour).

![Ff387983 Aeb9 4a03 Bbca 81baab6794df](https://content.hostman.com/assets/ceb30dc1-be83-4045-ae13-6c64ba485daf.png?width=1545&height=1040)

You can create multiple rules (e.g., allow different methods for different origins) by clicking **Add Rule**.

4.  Save the changes by clicking **Save**.
    

## Via AWS CLI

Here's how to set up CORS for an S3 bucket using the AWS CLI utility.

### Creating a CORS Rules File

First, create a `cors.json` file with the desired CORS configuration. This file will allow GET and HEAD requests to objects in your bucket. Here's an example:

```shell
{
  "CORSRules": [
    {
      "AllowedHeaders": ["*"],
      "AllowedMethods": ["GET", "HEAD"],
      "AllowedOrigins": ["*"]
    }
  ]
}
```

-   `AllowedMethods`: Specifies the HTTP methods allowed. In this example, GET and HEAD requests are permitted.
    
-   `AllowedOrigins`: `*` means requests are allowed from any domain. To restrict access to a specific domain, replace the asterisk with the domain name. For example, if your website is hosted at `https://example.com`, replace the line with:
    

```shell
"AllowedOrigins": ["https://example.com"]
```

### Uploading CORS Rules to the Bucket

After creating the CORS rules file, upload it to your S3 bucket using the following command:

```shell
aws s3api put-bucket-cors --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net --cors-configuration file://cors.json
```

Replace `<bucket_name>` with the name of your bucket.

### Verifying CORS Rules

To confirm that the CORS rules have been successfully applied, use this command:

```shell
aws s3api get-bucket-cors --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net
```

### Deleting CORS Rules

If you need to remove the current CORS rules, execute the following command:

```shell
aws s3api delete-bucket-cors --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net
```

This command will delete all existing CORS rules for the bucket.

# Manage Object Lifecycle

Source: https://hostman.com/docs/s3/supported-features/object-lifecycle/

When using [S3](https://hostman.com/products/s3-storage/), you may need to manage the lifecycle of objects to optimize resource usage and prevent storage overflow. To achieve this, you can configure lifecycle rules, which automatically delete objects after a specified number of days.

Here’s how to set up lifecycle rules for objects in an S3 bucket using the Hostman dashboard and the AWS CLI.

## Via the Dashboard

### Creating Rules

To create lifecycle rules:

1.  Go to the **S3 Storage** section and click on the bucket.
2.  In the **Settings** tab, click **Change** next to **Lifecycle**.

![Cdf1f9d8 689b 4713 Aec4 5fb1730689af](https://content.hostman.com/assets/b1bbf7a4-a554-4b3d-b13f-590b53146f1b.png?width=1547&height=1141)

3.  Click **Add rule**.
4.  Set up the parameters:

-   -   **Object prefix**. For example, if you set the prefix `logs/`, the rule will only apply to objects in the `logs` “folder.”
    -   **Action**. Choose what should happen to the objects and after how many days the action should be applied. Three options are available:
        -   **Delete any**: applies to any object in the bucket.
        -   **Delete non-current**: applies to old versions of objects (relevant if object versioning is enabled).
        -   **Abort incomplete upload**: automatically removes unfinished multipart uploads.

5.  Click **Save**.
    

![23ad3920 2560 4904 9d02 Ecb1da936265](https://content.hostman.com/assets/1edc4599-c528-40d0-85c1-675439e18965.png?width=1689&height=869)

### Managing Existing Rules

To view and manage all existing lifecycle rules:

1.  Go to the **S3 Storage** section and click on the bucket.
2.  In the **Settings** tab, click **Change** next to **Lifecycle**.

The window will display all existing rules, including those added through external tools such as the AWS CLI.

Here, you can:

-   **Delete a rule** by clicking the trash bin icon.
-   **Temporarily disable a rule** by toggling the switch.
-   **Edit a rule** by clicking on it to open the edit window.

![Fee1d050 Ea32 4ab6 B6e9 66f9996f2cb0](https://content.hostman.com/assets/da61e346-8195-4868-9b8c-1bb14a48b97d.png?width=1538&height=749)

## Via AWS CLI

### Creating a Lifecycle Rule File

To set up automatic deletion of files after a certain period, create a configuration file for the lifecycle rules. For example, if you want to store files in the logs folder for only **one day**, create a file named `lifecycle.json` with the following content:

```shell
{
  "Rules": [
    {
      "Status": "Enabled",
      "Filter": {"Prefix": "logs/"},
      "Expiration": {"Days": 1}
    }
  ]
}
```

-   `Prefix`: Specifies the folder (or prefix) to which the rule will apply. In this example, files in the `logs/` folder will be automatically deleted after one day.
    
-   `Expiration`: Defines the retention period in days. Here, files are deleted one day after upload.
    

### Adding Multiple Rules

You can add multiple rules for different folders or files. For instance, if you have another folder, `logs2`, where files should be stored for **two days**, simply add an additional rule:

```shell
{
  "Rules": [
    {
      "Status": "Enabled",
      "Filter": {"Prefix": "logs/"},
      "Expiration": {"Days": 1}
    },
    {
      "Status": "Enabled",
      "Filter": {"Prefix": "logs2/"},
      "Expiration": {"Days": 2}
    }
  ]
}
```

With this configuration:

-   Files in the `logs/` folder will be retained for one day.
-   Files in the `logs2/` folder will be retained for two days.

### Uploading Lifecycle Rules to a Bucket

After creating the lifecycle rule file, upload it to your S3 bucket using the following command:

```shell
aws s3api put-bucket-lifecycle-configuration --bucket <bucket_name> --lifecycle-configuration file://lifecycle.json --endpoint-url https://s3.hmstorage.net
```

This command applies the specified rules to your bucket, and files will be automatically deleted after the defined period.

### Verifying Lifecycle Rules

To ensure that the lifecycle rules were successfully applied, run the following command:

```shell
aws s3api get-bucket-lifecycle-configuration --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net
```

This will display the current lifecycle rules configured for your bucket.

### Removing Lifecycle Rules

If you need to delete all existing lifecycle rules for a bucket, execute the following command:

```shell
aws s3api delete-bucket-lifecycle --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net
```

This command removes all lifecycle rules, and files will no longer be automatically deleted.

# Object Versioning

Source: https://hostman.com/docs/s3/supported-features/object-versioning/

Versioning in S3 allows you to retain all changes made to objects uploaded to a bucket. It helps protect data from accidental deletion or overwrites and allows you to restore previous versions of objects when needed.

Versioning can be enabled using various clients, such as AWS CLI, S3 Browser, and others. This article covers working with versions using AWS CLI.

## Enabling Versioning

Versioning can be enabled through the dashboard or using clients such as AWS CLI, S3 Browser, and others.

### Using the Dashboard

1.  Go to the **S3 Storage** section and click on the bucket.
2.  Go to the **Settings** tab and click **Change** next to **Version history is disabled**.
    

![198b15da 7d64 460e Aff6 5bada42d5b26](https://content.hostman.com/assets/57386ace-b54d-459a-a679-e40b2c869396.png?width=1538&height=869)

3.  Confirm enabling versioning by clicking **Enable versioning**.
    

Note: Once enabled, versioning cannot be fully disabled for the bucket later; it can only be suspended.

### Using AWS CLI

To enable versioning on an S3 bucket using AWS CLI, run the following command:

```shell
aws s3api put-bucket-versioning --bucket <bucket_name> --versioning-configuration Status=Enabled --endpoint-url https://s3.hmstorage.net
```

To verify that versioning is enabled, use:

```shell
aws s3api get-bucket-versioning --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net
```

Expected output:

```shell
{
    "Status": "Enabled",
    "MFADelete": "Disabled"
}
```

## Testing Versioning

Let's demonstrate how versioning works with an example.

1.  Create a test file:
    

```shell
echo "Version 1" > testfile.txt
```

2.  Upload it to the bucket:
    

```shell
aws s3 cp testfile.txt s3://<bucket_name>/ --endpoint-url https://s3.hmstorage.net
```

3.  Update the file:
    

```shell
echo "Version 2" > testfile.txt
```

4.  Upload it again:
    

```shell
aws s3 cp testfile.txt s3://<bucket_name>/ --endpoint-url https://s3.hmstorage.net
```

Now the file has multiple versions. To check them, use:

```shell
aws s3api list-object-versions --bucket <bucket_name> --prefix testfile.txt --endpoint-url https://s3.hmstorage.net
```

Example output:

```shell
{
    "Versions": [
        {
            "Key": "testfile.txt",
            "VersionId": "S7hpDH6F0RYfubNoTjin6hpBu5ewDj.",
            "IsLatest": true
        },
        {
            "Key": "testfile.txt",
            "VersionId": "pdFehsuCbaPz2hNh4b9DBndfEwzjTfH",
            "IsLatest": false
        }
    ]
}
```

#### Important Notes

-   Each object version takes up storage space in the bucket.
-   Object versions are not displayed in the dashboard or other S3 clients.
-   Even if an object is deleted, all its versions remain in the bucket.

## Working with Versions in the Dashboard

To view a list of object versions in the dashboard:

1.  Go to the **S3 Storage** section and click on the bucket.
2.  Open the **Objects** tab.
3.  Click the three dots next to the object and select **Version history**.
4.  Hover over a version to see available actions:
    -   **File link** generates a presigned URL for this object version.
    -   **Downloading** allows to download the selected version.
    -   **Restoring object version** makes the selected version the current version.
    -   **Deleting object version** (by clicking on the three dots) allows to delete the chosen version.

## Managing Object Versions

There are several commands available for managing object versions.

### List All Versions of a Specific Object

```shell
aws s3api list-object-versions --bucket <bucket_name> --prefix <object_name> --endpoint-url https://s3.hmstorage.net
```

### List All Objects and Versions

```shell
aws s3api list-object-versions --bucket <bucket_name> --query 'Versions[*].[Key, VersionId, Size]' --endpoint-url https://s3.hmstorage.net
```

### Downloading a Specific Object Version

To download a specific version of an object, use:

```shell
aws s3api get-object --bucket <bucket_name> \
                     --key testfile.txt \
                     --version-id pdFehsuCbaPz2hNh4b9DBndfEwzjTfH \
                     testlocalfile.txt \
                     --endpoint-url https://s3.hmstorage.net
```

Where:

-   `--key` – The object name in the bucket.
-   `--version-id` – The version ID (retrieved using `list-object-versions`).
-   `testlocalfile.txt` – The name of the file where the downloaded version will be saved.

### Restoring a Specific Object Version

If an object was updated or deleted, you can restore a previous version by copying it over the current one:

```shell
aws s3api copy-object --bucket <bucket_name> \
                      --key testfile.txt \
                      --copy-source <bucket_name>/<object_name>?versionId=<version_id> \
                      --endpoint-url https://s3.hmstorage.net
```

Where:

-   `<bucket_name>/<object_name>` – Full path to the object in the bucket.
-   `?versionId=<version_id>` – The version to be restored.

This command will create a new version in the bucket identical to the restored one.

### Deleting a Specific Object Version

To delete a specific version of an object, use:

```shell
aws s3api delete-object --bucket <bucket_name> --key <object_name> --version-id S7hpDH6F0RYfubNoTjin6hpBu5ewDj. --endpoint-url https://s3.hmstorage.net
```

Where `--version-id` is the ID of the object version to be deleted.

### Configuring Automatic Deletion of Old Versions

To prevent old file versions from accumulating, you can set up an [object lifecycle](https://hostman.com/docs/s3/supported-features/object-lifecycle/) policy.

1.  Create a file called `lifecycle.json`:
    

```shell
{
    "Rules": [
        {
            "ID": "DeleteOldVersions",
            "Status": "Enabled",
            "Filter": {},
            "NoncurrentVersionExpiration": {
                "NoncurrentDays": 30
            }
        }
    ]
}
```

This rule deletes object versions older than 30 days while keeping the current versions intact.

2.  Apply the lifecycle policy:
    

```shell
aws s3api put-bucket-lifecycle-configuration --bucket <bucket_name> --lifecycle-configuration file://lifecycle.json --endpoint-url https://s3.hmstorage.net
```

3.  Verify that the policy has been applied:
    

```shell
aws s3api get-bucket-lifecycle-configuration --bucket <bucket_name> --endpoint-url https://s3.hmstorage.net
```

# Object Lock

Source: https://hostman.com/docs/s3/supported-features/object-lock/

Object Lock is used to protect objects in S3 from deletion and modification for a specified period. This feature ensures data immutability throughout the storage duration. Object Lock is especially useful for working with important archives, backups, and other critical information that needs protection from accidental or intentional actions.

## Creating a Bucket with Object Lock

Object Lock can only be enabled when creating a bucket. Currently, this feature cannot be enabled through the management console, so the bucket must be created using third-party clients or tools. Below is an example of creating a bucket via AWS CLI.

Create a bucket:

```shell
aws s3api create-bucket \
	--bucket object-lock-bucket \
	--endpoint-url https://s3.hmstorage.net \
	--object-lock-enabled-for-bucket
```

You can also create a bucket with a cold storage class:

```shell
aws s3api create-bucket \
	--bucket object-lock-bucket \
	--endpoint-url https://s3.hmstorage.net \
	--create-bucket-configuration LocationConstraint=us:us-2-cold \
	--object-lock-enabled-for-bucket
```

> [!NOTE]
> You cannot specify the bucket size at the time of creation. When creating a bucket through third-party clients, the minimum possible size is always set: 10 GB for the standard storage class and 1 GB for the cold storage class. After the bucket is created, its size can be increased through the dashboard.

To verify that Object Lock is enabled, run:

```shell
aws s3api get-object-lock-configuration \
  --bucket object-lock-bucket \
  --endpoint-url https://s3.hmstorage.net
```

Expected response:

```shell
{
	"ObjectLockConfiguration": {
    	"ObjectLockEnabled": "Enabled"
	}
}
```

Object Lock only works if versioning is enabled. To check if versioning is active, run:

```shell
aws s3api get-bucket-versioning \
  --bucket object-lock-bucket \
  --endpoint-url https://s3.hmstorage.net
```

The response will show the versioning status:

```shell
{
	"Status": "Enabled",
	"MFADelete": "Disabled"
}
```

## Object Lock Modes

Object Lock supports two modes of object protection:

1.  **COMPLIANCE Mode** – A strict protection mode. The object and its versions cannot be deleted or modified until the lock period expires. Even with administrator privileges and special permissions, data deletion is impossible. This mode is suitable for scenarios where data immutability is critical.
    
2.  **GOVERNANCE Mode** – A flexible protection mode. Objects are protected from deletion and modification, but users with the BypassGovernanceRetention permission can delete data before the lock period expires. This mode is useful for preventing accidental deletions.
    

> [!NOTE]
> In the current S3 storage implementation, only one user is created with full permissions, including `BypassGovernanceRetention`. Therefore, when using GOVERNANCE Mode, this user will always be able to delete objects by bypassing the lock.

## Using Object Lock

Let's go through examples of working with the COMPLIANCE and GOVERNANCE modes.

### COMPLIANCE Mode

Upload a file with a 30-day lock:

```shell
aws s3api put-object \
	--bucket object-lock-bucket \
	--key compliance-file.txt \
	--body compliance-file.txt \
	--object-lock-mode COMPLIANCE \
	--object-lock-retain-until-date "$(date -d '+30 days' --utc +%Y-%m-%dT%H:%M:%SZ)" \
	--endpoint-url https://s3.hmstorage.net
```

Parameter descriptions:

-   `--bucket` – Name of the bucket where the object is uploaded.
-   `--key` – Name (path) of the object in the bucket.
-   `--body` – Path to the file being uploaded.
-   `--object-lock-mode` – Lock mode.
-   `--object-lock-retain-until-date` – Lock expiration date in `YYYY-MM-DDTHH:MM:SSZ` format. The object cannot be deleted before this date.

Verify that the lock is applied:

```shell
aws s3api get-object-retention \
  --bucket object-lock-bucket \
  --key compliance-file.txt \
  --endpoint-url https://s3.hmstorage.net
```

Expected output:

```shell
{
	"Retention": {
    	"Mode": "COMPLIANCE",
    	"RetainUntilDate": "2025-04-04T10:02:21.000000000Z"
	}
}
```

Now let's attempting to delete the object:

```shell
aws s3api delete-object \
  --bucket object-lock-bucket \
  --key compliance-file.txt \
  --endpoint-url https://s3.hmstorage.net
```

The file will disappear from the **Objects** tab in the dashboard and from third-party clients. A deletion marker will be created, but the object remains in the bucket.

Check object versions:

```shell
aws s3api list-object-versions \
  --bucket object-lock-bucket \
  --prefix compliance-file.txt \
  --endpoint-url https://s3.hmstorage.net
```

The version will be saved, and a deletion marker will be created. The deleted version can be restored following the [recovery instructions](https://hostman.com/docs/s3/supported-features/object-versioning/#restoring-a-specific-object-version).

You won't be able to delete a specific version with an active lock:

```shell
aws s3api delete-object \
  --bucket object-lock-bucket \
  --key compliance-file.txt \
  --version-id <VersionId_of_object> \
  --endpoint-url https://s3.hmstorage.net
```

Until the lock expiration date, the command will return an error:

```shell
An error occurred (AccessDenied) when calling the DeleteObject operation: forbidden by object lock
```

### GOVERNANCE Mode

Upload a file with a 30-day lock:

```shell
aws s3api put-object \
	--bucket object-lock-bucket \
	--key governance-file.txt \
	--body governance-file.txt \
	--object-lock-mode GOVERNANCE \
	--object-lock-retain-until-date "$(date -d '+30 days' --utc +%Y-%m-%dT%H:%M:%SZ)" \
	--endpoint-url https://s3.hmstorage.net
```

Parameter descriptions:

-   `--bucket` – Name of the bucket where the object is uploaded.
-   `--key` – Name (path) of the object in the bucket.
-   `--body` – Path to the file being uploaded.
-   `--object-lock-mode` – Lock mode.
-   `--object-lock-retain-until-date` – Lock expiration date in `YYYY-MM-DDTHH:MM:SSZ` format. The object cannot be deleted before this date.

Verify that the lock is applied:

```shell
aws s3api get-object-retention \
  --bucket object-lock-bucket \
  --key governance-file.txt \
  --endpoint-url https://s3.hmstorage.net
```

Expected output:

```shell
{
	"Retention": {
    	"Mode": "GOVERNANCE",
    	"RetainUntilDate": "2025-04-04T10:07:44.000000000Z"
	}
}
```

Try to delete the object:

```shell
aws s3api delete-object \
  --bucket object-lock-bucket \
  --key governance-file.txt \
  --endpoint-url https://s3.hmstorage.net
```

The file will disappear from the **Objects** tab in the dashboard and third-party clients. A deletion marker will be created, but the object remains in the bucket.

Check object versions:

```shell
aws s3api list-object-versions \
  --bucket object-lock-bucket \
  --prefix governance-file.txt \
  --endpoint-url https://s3.hmstorage.net
```

The object's version and deletion marker will be visible. The deleted version can be restored following the [recovery instructions](https://hostman.com/docs/s3/supported-features/object-versioning/#restoring-a-specific-object-version).

Let's try deleting an object with lock bypass. Unlike COMPLIANCE mode, objects in GOVERNANCE mode can be deleted before the lock expires using the `--bypass-governance-retention` flag.

```shell
aws s3api delete-object \
  --bucket object-lock-bucket \
  --key governance-file.txt \
  --bypass-governance-retention \
  --version-id <VersionId_of_object> \
  --endpoint-url https://s3.hmstorage.net
```

Now, check the object versions again:

```shell
aws s3api list-object-versions \
  --bucket object-lock-bucket \
  --prefix governance-file.txt \
  --endpoint-url https://s3.hmstorage.net
```

Only the deletion marker will be displayed.

# Configure Object Headers

Source: https://hostman.com/docs/s3/supported-features/object-headers/

This guide explains how to set headers for [S3](https://hostman.com/products/s3-storage/) objects using `s3cmd` and `aws s3api`. This is useful for managing caching, adding custom metadata, and optimizing bucket data handling.

## Setting Headers via Dashboard

1.  Go to the **S3 storage** section and click on the bucket.
2.  In the **Objects** tab, click on the three dots next to the object and select **Edit metadata**.

![36d71125 Cdfd 41b2 9810 540c7c9b4883](https://content.hostman.com/assets/27221b6d-52c6-4d89-932f-793afd7572c1.png?width=1543&height=868)

3.  Add necessary headers. To set up a custom header, click **+Add**.

![Bacf7b83 9ffc 4c5b Ac07 5dd516c23d0d](https://content.hostman.com/assets/50adcfe9-1085-4745-ae5f-1ccdc80ef565.png?width=1548&height=867)

### Available Parameters

You can configure the following parameters.

#### Content-Type

The MIME type of the object's content. It defines the file format and is used by client applications to process the file correctly.

Example values:

-   `application/pdf`: PDF document
-   `image/jpeg`: JPEG image
-   `text/plain`: plain text file
-   `application/json`: JSON document

If an incorrect value is set, browsers or applications may fail to identify the file type properly.

#### Cache-Control

Controls how the object is cached by browsers, CDNs, and intermediate proxy servers.

Example: `max-age=3600`

In this case, the object can be stored in cache for 3600 seconds (1 hour) without making a new request to the storage.

#### Content-Encoding

Specifies the encoding applied to the object's content.

Example: `gzip`

Used for files that were compressed before being uploaded to storage. When the object is retrieved, the client can automatically decompress the content.

#### Content-Disposition

Defines how the file is handled when downloaded.

Common values:

-   `attachment`: prompt the user to save the file
-   `inline`: attempt to open the file directly in the browser

For example, for PDF documents, inline opens the file in a browser tab, while attachment triggers a download.

#### Custom Metadata

Lets you attach arbitrary key-value pairs to an object.

To add custom metadata, click **Add** and fill in the fields:

-   `Key`: the metadata name. Custom metadata keys are stored with the `x-amz-meta-` prefix.
-   `Value`: an arbitrary metadata value.

Examples:

| **Key** | **Value** |
| --- | --- |
| `project` | `website` |
| `owner` | `marketing` |
| `version` | `1.2` |

You can add multiple custom metadata entries to a single object.

Custom metadata does not affect file contents, but can be used by applications to store additional information about an object, classify it, or drive processing logic.

## Setting Headers via CLI

Another way to configure headers is to use utilities like `s3cmd` or `s3api`.

### Setting a Header for a Single Object

To set a header for a specific object, use the `s3cmd modify` command. For example, to add a Cache-Control header to a specific object:

```shell
s3cmd modify s3://<bucket_name>/<object_name> --add-header="cache-control:max-age=7000"
```

In this case, the object will receive the `Cache-Control` header with the `max-age=7000` parameter, instructing browsers or proxy servers to cache the object for 7000 seconds.

### Setting Headers for All Objects in a Bucket

To set headers for all objects in a bucket, you can use the `--recursive` option to apply changes to all files:

```shell
s3cmd modify --recursive s3://<bucket_name> --add-header="cache-control:max-age=7001"
```

This command recursively adds the `Cache-Control` header with the value `max-age=7001` to all objects in the bucket.

### Creating a Custom Header

To add custom headers, use the `s3cmd modify` command with the `x-amz-meta` prefix:

```shell
s3cmd modify s3://<bucket_name>/<object_name> --add-header="x-amz-meta-test-header:test"
```

This creates a custom header `x-amz-meta-test-header` with the value `test`. In the object's metadata, the header will appear without the `x-amz-meta-` prefix, resulting in:

```shell
"Metadata": {
    "test-header": "test"
}
```

This allows you to store additional data in the object, which can be useful for processing or logging.

### Verifying Set Headers

To verify the headers, use the `aws s3api head-object` command. This ensures that all headers and metadata have been successfully added:

```shell
aws s3api head-object --bucket <bucket_name> --key <object_name> --endpoint-url https://s3.hmstorage.net
```

The command will return information about the object, including its metadata and headers, allowing you to confirm that the changes were applied correctly.

# Configure Bucket Policies

Source: https://hostman.com/docs/s3/supported-features/bucket-policies/

[S3](https://hostman.com/products/s3-storage/) access management features enable flexible configuration of access rules for various use cases. Below are some useful examples of S3 bucket policy configurations.

## Restricting Access to HTTPS Only

To secure data transmission, you can restrict bucket access to HTTPS connections only. This prevents access attempts using unsecured HTTP requests, reducing the risk of data compromise.

1.  Create a policy file named `ssl.json`:
    

```shell
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Deny",
            "Principal": "*",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::<bucket_name>/*",
            "Condition": {
                "Bool": {
                    "aws:SecureTransport": "false"
                }
            }
        }
    ]
}
```

2.  Apply the policy using the following command:
    

```shell
aws s3api put-bucket-policy --bucket <bucket_name> --policy file://ssl.json --endpoint-url https://s3.hmstorage.net
```

Now, any HTTP requests will return a 403 error.

## Restricting Access by IP Addresses

To enhance security, you can limit bucket access to specific IP addresses. This is useful for protecting data from unauthorized external access.

1.  Create a policy file named `ip.json`:
    

```shell
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::<bucket_name>/*",
            "Condition": {
                "IpAddress": {
                    "aws:SourceIp": [
                        "<IP_address>"
                    ]
                }
            }
        }
    ]
}
```

2.  Apply the policy using the following command:
    

```shell
aws s3api put-bucket-policy --bucket <bucket_name> --policy file://ip.json --endpoint-url https://s3.hmstorage.net
```

## Granting Access to a Specific Prefix

If you need to provide access to specific objects in a bucket, such as files under a certain prefix, use the following policy. This is ideal for private buckets to allow access only to specific data.

1.  Create a policy file named `prefix.json`:
    

```shell
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::<bucket_name>/html/*"
        }
    ]
}
```

2.  Apply the policy using the following command:
    

```shell
aws s3api put-bucket-policy --bucket <bucket_name> --policy file://prefix.json --endpoint-url https://s3.hmstorage.net
```

Now, all files under the `/html` prefix will be accessible for reading.

# Multipart Upload

Source: https://hostman.com/docs/s3/supported-features/multipart-upload/

Multipart upload is a method of transferring large files to [S3 storage](https://hostman.com/products/s3-storage/) by splitting the file into smaller parts (chunks) and uploading them in parallel. This approach speeds up the process and improves reliability: in the event of a failure, you only need to re-upload the corrupted part instead of the entire file. It is especially useful for handling large files and working with unstable network connections.

## Advantages of Multipart Upload

-   **Faster Data Transfer**: Parallel uploads of multiple parts reduce the time required to transfer large files.
-   **Flexibility**: The ability to pause and resume uploads makes it easier to work with unstable connections.
-   **Fault Tolerance**: Errors during the transfer of individual parts can be fixed by re-uploading just those parts.

> [!NOTE]
> Note: If a multipart upload is interrupted, the incomplete file parts won’t appear in the bucket interface but will still occupy storage space on the server. To free up this space, you need to manually finalize or cancel the upload.

## Use Cases

Many tools and libraries for working with [S3](https://hostman.com/products/s3-storage/) support multipart uploads and allow you to configure the size of the parts. Below are some tools that support multipart uploads:

-   [AWS CLI](https://hostman.com/docs/s3/tools/aws-cli/#multipart-upload)
-   [s3cmd](https://hostman.com/docs/s3/tools/s3cmd/#managing-interrupted-multipart-uploads)
-   [S3 Browser](https://hostman.com/docs/s3/tools/s3-browser/#managing-interrupted-multipart-uploads)

These tools provide flexible options for configuring the upload process, enabling you to optimize data transfer based on your needs and network conditions.

# Configure S3 Proxying via Nginx

Source: https://hostman.com/docs/s3/supported-features/configuring-s3-proxying-via-nginx/

Proxying S3 through Nginx allows you to use your server as an intermediary between clients and the S3 storage, providing multiple benefits. You can hide direct access to S3, control caching to optimize traffic, modify headers for flexible request handling, and restrict access to content. Additionally, a proxy helps unify access to multiple services under a single domain, reduce traffic costs through local caching, and enable detailed request logging for analysis.

## Installing Nginx

First, install Nginx if you don’t have it yet:

```shell
sudo apt update
sudo apt install nginx
```

Check Nginx is running using the command:

```shell
sudo systemctl status nginx
```

If it’s not, start the service and enable it to launch at system boot:

```shell
sudo systemctl start nginx
sudo systemctl enable nginx
```

## Configuring Bucket Access

For proxying to work, your bucket must be **public** or have **configured access** for your server's IP address.

To allow access to the bucket from your server's IP, set a bucket policy using AWS CLI. First, create a file named `bucket-policy.json` with the following content.

```shell
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::bucket_name/*",
      "Condition": {
        "IpAddress": {
          "aws:SourceIp": "server_IP_address"
        }
      }
    }
  ]
}
```

Specify the parameters:

-   `bucket_name` — Your bucket name.
-   `server_IP_address` — The external IP address of your server.

Apply the policy to the bucket:

```shell
aws s3api put-bucket-policy --bucket bucket_name --policy file://bucket-policy.json --endpoint-url https://s3.hmstorage.net
```

If you need to allow multiple IP addresses, add them as an array in the `IpAddress` field:

```shell
"IpAddress": {
  "aws:SourceIp": ["IP_address_1", "IP_address_2"]
}
```

Now, the bucket will only be accessible from the specified IP addresses.

## Basic Configuration

Create a configuration file for proxying. For example, create a file `s3_proxy.conf` in `/etc/nginx/sites-available`:

```shell
sudo nano /etc/nginx/sites-available/s3_proxy.conf
```

Configure it as follows:

```shell
server {
    listen 80;
    server_name your_domain;

    location / {
        proxy_pass https://s3.hmstorage.net/bucket_name/;
        proxy_set_header Host s3.hmstorage.net;
        proxy_ssl_server_name on;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Authorization "";
        proxy_hide_header x-amz-id-2;
        proxy_hide_header x-amz-request-id;
        proxy_hide_header Set-Cookie;
        add_header Cache-Control "public, max-age=3600";
        expires 1h;
    }
}
```

Save the file and create a symbolic link in `sites-enabled`:

```shell
sudo ln -s /etc/nginx/sites-available/s3_proxy.conf /etc/nginx/sites-enabled/
```

Check the configuration for errors:

```shell
sudo nginx -t
```

If no errors are found, restart Nginx:

```shell
sudo systemctl restart nginx
```

Now, files from the bucket will be available at `http://your_domain/file_name`.

## Setting Up an SSL Certificate for the Proxy

For increased security, configure HTTPS using Certbot. Install Certbot and the Nginx plugin:

```shell
sudo apt install certbot python3-certbot-nginx
```

Generate and install the SSL certificate:

```shell
sudo certbot --nginx -d your_domain
```

Certbot will automatically update the Nginx configuration for HTTPS. Once completed, Certbot will activate the certificate, and the proxy will start working over a secure connection.

# Presigned URL

Source: https://hostman.com/docs/s3/supported-features/presigned-url/

A **Presigned URL** in S3 allows temporary access to an object in storage without the need to change the object's access permissions. It is a convenient tool for downloading files by third-party users. In this article, we will look at how to create a Presigned URL in two ways: in the Hostman dashboard or via AWS CLI.

## In the Hostman Dashboard

Presigned URL generation is only available for private buckets. To generate a Presigned URL:

1.  Go to the **S3 storage** section and click on the bucket.
2.  In the **Objects** tab, hover over the object and click the **File link** button.

![0a12ff53 9cb4 4b16 A2fa 1166627866cc](https://content.hostman.com/assets/c2a3524d-63ae-46e1-87b7-0b238cb687d4.png?width=1568&height=867)

The link will be copied to the clipboard and will remain active for 60 minutes. After that, the link will return a 500 error. The dashboard does not allow changing this parameter.

You can also generate a link for a specific object version if [versioning is enabled](https://hostman.com/docs/s3/supported-features/object-versioning/) on the bucket. To do this:

1.  Click the three dots next to the object and select **Version history**. 
2.  Click **File link** next to the desired version.

## Via AWS CLI

You can create a Presigned URL using AWS CLI with the following command:

```shell
aws s3 presign s3://<bucket>/<object> --expires-in 60 --endpoint-url https://s3.hmstorage.net
```

The `--expires-in` parameter is optional. It defines how long the object will be available via the link (in seconds). If the parameter is not specified, the object will be available for 3600 seconds (1 hour).

Standard utilities do not support generating a presigned URL for a version other than the current one. To create a link for a specific object version, you can use custom scripts. For example, the following Python script can be used:

```py
#!/usr/bin/env python3
import argparse
import boto3

parser = argparse.ArgumentParser()
parser.add_argument('--bucket', required=True)
parser.add_argument('--key', required=True)
parser.add_argument('--expires-in', type=int, default=3600)
parser.add_argument('--version-id')
parser.add_argument('--method', default='get_object')
args = parser.parse_args()

client = boto3.client('s3', endpoint_url='https://s3.hmstorage.net')
params = {'Bucket': args.bucket, 'Key': args.key}

if args.version_id:
    params.update({'VersionId': args.version_id})

url = client.generate_presigned_url(args.method, Params=params, ExpiresIn=args.expires_in)

print(url)
```

Run the script with:

```shell
python ./main.py --bucket <bucket-name> --key <object-key> --expires-in 6969 --version-id <object-version>
```

Where:

-   `--expires-in` is time in seconds until the link expires.
-   `--version-id` is the object version (`VersionId`), which can be obtained, for example, via AWS CLI.

The script will take authentication credentials from `~/.aws/credentials`.

### Generating a Presigned URL for Object Upload

You can pre-generate a presigned URL for uploading an object, even if the object does not yet exist in the bucket. Standard utilities like AWS CLI do not support this, but it can be done via an SDK, such as `boto3` for Python.

Example script:

```py
import boto3
from botocore.client import Config

# Enter your credentials
AWS_ACCESS_KEY_ID = 'S3 Access Key'
AWS_SECRET_ACCESS_KEY = 'S3 Secret Access Key'
BUCKET_NAME = 'Bucket Name'
OBJECT_KEY = 'example.txt'  # name of the future object
EXPIRES_IN = 3600  # link expiration time in seconds

s3 = boto3.client(
    's3',
    endpoint_url='https://s3.hmstorage.net',
    aws_access_key_id=AWS_ACCESS_KEY_ID,
    aws_secret_access_key=AWS_SECRET_ACCESS_KEY,
    config=Config(signature_version='s3v4'),
    region_name='us-2'
)

# Generate presigned URL
url = s3.generate_presigned_url(
    ClientMethod='put_object',
    Params={
        'Bucket': BUCKET_NAME,
        'Key': OBJECT_KEY,
    },
    ExpiresIn=EXPIRES_IN
)

print(url)
```

Note: You do not need to specify `Content-Type` when generating the link, as including it may cause an error.

After running the script, a temporary upload link will be generated.

You can upload the file using `curl`:

```shell
curl -X PUT -T /path/to/file.txt -H "Content-Type: text/plain" "<presigned-url-from-script>"
```

# Static Websites

Source: https://hostman.com/docs/s3/supported-features/static-websites/

With S3 storage, you can host a static website. This is convenient, for example, for publishing documentation, a portfolio, or a landing page.

## Configuration

To host a website:

1.  Upload the index file to the root of the bucket. It must not be placed inside a folder.
    
2.  The rest of the files (pages, styles, scripts, media content) can be placed in directories.
    

Example structure:

```shell
index.html
pages/
  firstpage.html
  secondpage.html
img/
  1.png
  2.png
css/
  style.css
js/
  index.js
404.html
403.html
```

Files can be uploaded through the object manager or using third-party utilities, such as Cyberduck.

After uploading:

1.  Go to the **Settings** section of the bucket.
2.  Click the **Change** button next to **Website**.

![42ff6636 B993 4423 B676 98a4aadd3313](https://content.hostman.com/assets/b0d4ade1-b5f8-401a-b47c-9b250723ebdc.png?width=1572&height=1230)

3.  Enable the static website.
4.  (Optional) Change the name of the index file (default: `index.html`).
5.  (Optional) Configure error pages: select an error code (for example, 404) and the corresponding page.
6.  Copy the link where your website will be available.
7.  Save the changes.

![4fe392fe 911e 4ffb 9e3f D13347e8956d](https://content.hostman.com/assets/5f390de4-08c8-475b-a24a-c75500707c76.png?width=1541&height=823)

## Limitations

-   At the moment, you cannot connect a custom domain. The site will only be available at an address like:

```shell
bucket_name.website.hmstorage.net
```

-   For the site to work, the bucket must be public. If you make it private, the pages will start returning a 403 error.

# Using S3 SDKs

Source: https://hostman.com/docs/s3/sdk/

S3 SDKs are libraries that allow you to work with object storage directly from your application code. Using an SDK, you can perform the same operations as with S3 command-line tools, such as uploading and downloading files, listing objects, deleting objects, and generating pre-signed URLs.

This section provides examples of using S3 SDKs in different programming languages:

-   [Python](https://hostman.com/docs/s3/sdk/python/)
-   [Node.js](https://hostman.com/docs/s3/sdk/javascript/)
-   [PHP](https://hostman.com/docs/s3/sdk/php/)

# Python

Source: https://hostman.com/docs/s3/sdk/python/

[boto3](https://pypi.org/project/boto3/) is the official Amazon SDK for working with S3 in Python. It allows you to manage objects in storage: upload and download files, list objects, work with metadata, perform multipart uploads, and generate pre-signed URLs. 

## Installation

To install `boto3`, use `pip`:

```shell
pip install boto3
```

After installation, the library is ready to use in your Python code.

## Configuring Access

When using `boto3`, access credentials can be configured in several ways.

### Using ~/.aws/config and ~/.aws/credentials

When you use the [AWS CLI](https://hostman.com/docs/s3/tools/aws-cli/), a `.aws` directory containing configuration files is automatically created in the user’s home directory. If necessary, you can create this directory and the files manually without installing the AWS CLI.

The `~/.aws/credentials` file should contain the following:

```shell
[default]
aws_access_key_id = <ACCESS_KEY>
aws_secret_access_key = <SECRET_KEY>
```

And `~/.aws/config`:

```shell
[default]
output = json
endpoint_url = https://s3.hmstorage.net
region = us-2
```

If you use the `default` profile, no additional configuration is required in the code; `boto3` will automatically load these settings.

### Using Environment Variables

You can also provide access credentials via environment variables:

```shell
export AWS_ACCESS_KEY_ID=<ACCESS_KEY>
export AWS_SECRET_ACCESS_KEY=<SECRET_KEY>
```

### Passing Credentials in Code

Credentials can be passed directly when creating the S3 client:

```py
import boto3

s3 = boto3.client(
    "s3",
    aws_access_key_id="<ACCESS_KEY>",
    aws_secret_access_key="<SECRET_KEY>",
    endpoint_url="https://s3.hmstorage.net",
    region_name="us-2"
)
```

This approach is not recommended for production, as access keys are stored directly in the source code.

### Using Named Profiles

If multiple profiles are configured in `~/.aws/config` and `~/.aws/credentials`, you can explicitly specify the required profile when creating a session:

```py
import boto3

session = boto3.Session(profile_name="myprofile")
s3 = session.client("s3")
```

This is useful when the same codebase is used to work with multiple buckets or environments.

## Example

Below is an example demonstrating basic object operations using the SDK. The script performs the following actions:

-   uploads a file to a bucket;
-   lists all objects in the bucket;
-   downloads the uploaded file under a different name;
-   deletes the object from storage.

Before running the script, create a file named `example.txt` in the same directory as the script.

Example code:

```py
import boto3
import os

bucket_name = "bucket_name"
endpoint_url = "https://s3.hmstorage.net"
local_upload_path = "example.txt"
s3_key = "example.txt"
local_download_path = "downloaded_example.txt"

# Create S3 client
s3 = boto3.client("s3", endpoint_url=endpoint_url)

# 1. Upload file to the bucket
if os.path.exists(local_upload_path):
    print(f"Uploading {local_upload_path} to the bucket...")
    s3.upload_file(local_upload_path, bucket_name, s3_key)
    print("Upload completed.")
else:
    print(f"File {local_upload_path} not found. Skipping upload.")

# 2. List objects in the bucket
print("\nBucket contents:")
paginator = s3.get_paginator("list_objects_v2")
for page in paginator.paginate(Bucket=bucket_name):
    for obj in page.get("Contents", []):
        print(f"- {obj['Key']}")

# 3. Download file from the bucket
print(f"\nDownloading {s3_key} to {local_download_path}...")
s3.download_file(bucket_name, s3_key, local_download_path)
print("Download completed.")

# 4. Delete file from the bucket
print(f"\nDeleting {s3_key} from the bucket...")
s3.delete_object(Bucket=bucket_name, Key=s3_key)
print("Deletion completed.")
```

# JavaScript

Source: https://hostman.com/docs/s3/sdk/javascript/

[@aws-sdk/client-s3](https://www.npmjs.com/package/@aws-sdk/client-s3) is the official AWS SDK library for working with the S3 service in JavaScript. It allows you to upload and download files, list and delete objects, perform multipart uploads, and generate pre-signed URLs.

## Installation

Install the package using `npm` or `yarn`:

```shell
npm install @aws-sdk/client-s3
```

Or:

```shell
yarn add @aws-sdk/client-s3
```

## Configuring Access

When using `@aws-sdk/client-s3`, access credentials can be configured in several ways.

### Using ~/.aws/config and ~/.aws/credentials

When you use the [AWS CLI](https://hostman.com/docs/s3/tools/aws-cli/), a `.aws` directory containing configuration files is automatically created in the user’s home directory. If necessary, you can create this directory and the files manually without installing the AWS CLI.

The `~/.aws/credentials` file should contain the following:

```shell
[default]
aws_access_key_id = <ACCESS_KEY>
aws_secret_access_key = <SECRET_KEY>
```

And `~/.aws/config`:

```shell
[default]
output = json
endpoint_url = https://s3.hmstorage.net
region = us-2
```

### Using Environment Variables

Credentials can also be provided via environment variables:

```shell
export AWS_ACCESS_KEY_ID=<ACCESS_KEY>
export AWS_SECRET_ACCESS_KEY=<SECRET_KEY>
```

### Passing Credentials in Code

Full client configuration with all parameters explicitly specified:

```js
const { S3Client } = require("@aws-sdk/client-s3");

const s3 = new S3Client({
  region: "us-2",
  endpoint: "https://s3.hmstorage.net",
  credentials: {
    accessKeyId: "<ACCESS_KEY>",
    secretAccessKey: "<SECRET_KEY>"
  }
});
```

### Using an AWS CLI Profile

If multiple AWS CLI profiles are configured, you can select the required one using an environment variable:

```js
export AWS_PROFILE=myprofile
```

In this case, the client can be created without explicitly passing access keys:

```js
const s3 = new S3Client({
  region: "us-2",
  endpoint: "https://s3.hmstorage.net"
});
```

## Example

The example below demonstrates basic object operations using the SDK. The script performs the following actions:

-   uploads a file to a bucket;
-   lists all objects in the bucket;
-   downloads the uploaded file under a different name;
-   deletes the object from storage.

Before running the script, create a file named `example.txt` in the same directory as the script.

Example code:

```js
const {
  S3Client,
  ListObjectsV2Command,
  PutObjectCommand,
  GetObjectCommand,
  DeleteObjectCommand
} = require("@aws-sdk/client-s3");

const { createReadStream, createWriteStream, existsSync } = require("fs");
const { pipeline } = require("stream");
const { promisify } = require("util");

const pipe = promisify(pipeline);

const bucketName = "bucket_name";
const region = "us-2";
const endpoint = "https://s3.hmstorage.net";
const localUploadPath = "example.txt";
const s3Key = "example.txt";
const localDownloadPath = "downloaded_example.txt";

// Create S3 client
const s3 = new S3Client({
  region,
  endpoint,
});

async function main() {
  // 1. Upload file
  if (existsSync(localUploadPath)) {
    console.log(`Uploading ${localUploadPath} to the bucket...`);
    await s3.send(new PutObjectCommand({
      Bucket: bucketName,
      Key: s3Key,
      Body: createReadStream(localUploadPath),
    }));
    console.log("Upload completed.");
  } else {
    console.log(`File ${localUploadPath} not found. Skipping upload.`);
  }

  // 2. List objects
  console.log("\nBucket contents:");
  const list = await s3.send(new ListObjectsV2Command({ Bucket: bucketName }));
  (list.Contents || []).forEach((obj) => {
    console.log(`- ${obj.Key}`);
  });

  // 3. Download file
  console.log(`\nDownloading ${s3Key} to ${localDownloadPath}...`);
  const { Body } = await s3.send(new GetObjectCommand({
    Bucket: bucketName,
    Key: s3Key,
  }));
  if (Body) {
    await pipe(Body, createWriteStream(localDownloadPath));
    console.log("Download completed.");
  }

  // 4. Delete file
  console.log(`\nDeleting ${s3Key} from the bucket...`);
  await s3.send(new DeleteObjectCommand({ Bucket: bucketName, Key: s3Key }));
  console.log("Deletion completed.");
}

main().catch((err) => {
  console.error("Error while performing operations:", err);
});
```

# PHP

Source: https://hostman.com/docs/s3/sdk/php/

[aws/aws-sdk-php](https://github.com/aws/aws-sdk-php) is the official Amazon SDK for working with the S3 service in PHP. It allows you to perform basic object operations in S3, including uploading and downloading files, deleting objects, listing bucket contents, and generating pre-signed URLs.

## Installation

Install the library using Composer:

```shell
composer require aws/aws-sdk-php
```

After installation, the library will be located in the `vendor` directory. To use it, include the autoloader:

```shell
require 'vendor/autoload.php';
```

The SDK requires the PHP `ext-xml` extension to be installed.

Check whether the extension is available:

```shell
php -m | grep xml
```

If the extension is not installed, install it using your package manager:

-   Debian / Ubuntu: 
    

```shell
sudo apt install php-xml
```

-   Alpine:
    

```shell
apk add php8-xml
```

-   RHEL / CentOS:
    

```shell
sudo yum install php-xml
```

## Configuring Access

Access credentials can be configured in several ways.

### Using ~/.aws/config and ~/.aws/credentials

When you use the [AWS CLI](https://hostman.com/docs/s3/tools/aws-cli/), a `.aws` directory containing configuration files is automatically created in the user’s home directory. If necessary, you can create this directory and the files manually without installing the AWS CLI.

The `~/.aws/credentials` file should contain:

```shell
[default]
aws_access_key_id = <ACCESS_KEY>
aws_secret_access_key = <SECRET_KEY>
```

And `~/.aws/config`:

```shell
[default]
output = json
endpoint_url = https://s3.hmstorage.net
region = us-2
```

### Using Environment Variables

You can also provide credentials via environment variables:

```shell
export AWS_ACCESS_KEY_ID=<ACCESS_KEY>
export AWS_SECRET_ACCESS_KEY=<SECRET_KEY>
```

In this case, you can use the SDK without additional configuration:

```php
$s3 = new Aws\S3\S3Client([
    'region' => 'us-2',
    'version' => 'latest',
    'endpoint' => 'https://s3.hmstorage.net',
]);
```

### Passing Credentials in Code

Credentials can be explicitly provided when creating the client:

```php
use Aws\S3\S3Client;

$s3 = new S3Client([
    'region' => 'us-2',
    'version' => 'latest',
    'endpoint' => 'https://s3.hmstorage.net',
    'credentials' => [
        'key' => '<ACCESS_KEY>',
        'secret' => '<SECRET_KEY>',
    ],
]);
```

### Using a Different AWS CLI Profile

If multiple profiles are configured in `~/.aws/credentials`, you can specify the required one:

```php
$s3 = new S3Client([
    'profile' => 'myprofile',
    'region' => 'us-2',
    'version' => 'latest',
    'endpoint' => 'https://s3.hmstorage.net',
]);
```

## Example

The example below demonstrates basic object operations:

-   uploading a file to a bucket;
-   listing objects in the bucket;
-   downloading a file;
-   deleting an object.

Before running the script, create a file named `example.txt` in the same directory as the script.

Example code:

```php
<?php

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

$bucket = 'bucket_name';
$key = 'example.txt';
$localUpload = 'example.txt';
$localDownload = 'downloaded_example.txt';

$s3 = new S3Client([
    'region' => 'us-2',
    'version' => 'latest',
    'endpoint' => 'https://s3.hmstorage.net',
    'credentials' => [
        'key' => '<ACCESS_KEY>',
        'secret' => '<SECRET_KEY>',
    ],
]);

try {
    // 1. Upload file to the bucket
    if (file_exists($localUpload)) {
        echo "Uploading file $localUpload...\n";
        $s3->putObject([
            'Bucket' => $bucket,
            'Key' => $key,
            'SourceFile' => $localUpload,
        ]);
        echo "Upload completed.\n";
    } else {
        echo "File $localUpload not found. Skipping upload.\n";
    }

    // 2. List objects
    echo "\nBucket contents:\n";
    $result = $s3->listObjectsV2([
        'Bucket' => $bucket,
    ]);

    if (!empty($result['Contents'])) {
        foreach ($result['Contents'] as $object) {
            echo "- {$object['Key']}\n";
        }
    } else {
        echo "(Bucket is empty)\n";
    }

    // 3. Download file
    echo "\nDownloading $key to $localDownload...\n";
    $s3->getObject([
        'Bucket' => $bucket,
        'Key' => $key,
        'SaveAs' => $localDownload,
    ]);
    echo "Download completed.\n";

    // 4. Delete file
    echo "\nDeleting $key from the bucket...\n";
    $s3->deleteObject([
        'Bucket' => $bucket,
        'Key' => $key,
    ]);
    echo "Deletion completed.\n";

} catch (AwsException $e) {
    echo "Error: {$e->getMessage()}\n";
}
```

# VPC

Source: https://hostman.com/docs/vpc/

VPC (virtual private cloud) is a private network service that allows you to connect cloud resources with each other, isolate them from other services on your account, manage network settings and Internet access, set network sizes and assign IP addresses for services from the private network address range.

Currently, you can add the following services into private networks:

-   Cloud servers,
-   Cloud databases,
-   Load balancers,
-   Kubernetes clusters,
-   Backend and Docker Apps.

VPC is provided for free.

At the moment, we provide two types of private networks: 

-   OVN. Available in the USA;
-   BGP. Available in the Netherlands and Germany.

In your dashboard, OVN and BGP networks will have different icons:

![7536c883 A606 4a03 Bdc8 9e713923fa96](https://content.hostman.com/assets/cf491063-a419-415a-b496-95d34a8c8cf5.png?width=1581&height=830)

# Create VPC

Source: https://hostman.com/docs/vpc/create/

You can create a new VPC in the **Networks** → **Private Networks** section or when creating a new cloud service.

**To create a new private network:**

1.  Go to the **Networks** → **Private Networks** section and click **Create** or **Add network**.
    
2.  Select the region. 
    
3.  Set the address range for the subnet: you can leave the default value or specify your own.
    
4.  Enter the network name and comment if necessary.
    
5.  Click **Create**.
    

The newly created network will appear in the list of networks, and you can proceed to manage its settings and add services.

**To create a new private network when creating a new cloud service:**

1.  Start creating a new server, database or load balancer.
2.  In the **Network** section, select the **Add network** option. If necessary, specify the subnet address and size or leave the default values.

![Image3](https://content.hostman.com/assets/4127029e-0e32-46d3-9d92-a20908f55bea?width=773&height=486)

3.  Finish creating the service.

The network will be created along with the cloud service, and you can find it in the **Private Networks** section. The service will be automatically added to this network.

# Add and Remove Services

Source: https://hostman.com/docs/vpc/add-remove-services/

There are several ways to add a service to a private network.

## Adding Services to VPC

You can add a cloud service to an existing private network:

-   In the **Networks** → **Private Networks** section
-   In a server’s settings
-   When creating a new service

### In "Private Networks"

1.  In the **Networks** → **Private Networks** section click on the network.
    
2.  Click **Add** in the **Services** block.
    
3.  Select **New** or **Existing** depending on whether the service already exists in the dashboard.
    

-   **New**: Select the service type: server, database, or load balancer.
    

![Image16](https://content.hostman.com/assets/f842cd78-331d-44b1-9614-726f15f89108?width=1492&height=842)

You will be redirected to the service creation page, where the required network will already be selected in the **Network** step. 

Complete creating the service. The IP address for the service will be issued automatically.

1.  -   **Existing**: Select the service you want to add to VPC and click **Add**.
        

> [!NOTE]
> Please note that the cloud server's public IP address may be changed.

![Image10](https://content.hostman.com/assets/9672e294-890a-46e1-bc21-8922a33ff97f?width=1494&height=838)

Hostman will start transferring the service to this VPC. Usually, it takes about one minute to transfer 10 GB. After the transfer is completed, the service will be restarted, with the total downtime of 5-10 minutes.

### In Server’s Settings

> [!NOTE]
> The server's public IP address may be changed.

To add a server to a private network: 

1.  Go to **Cloud Servers** and click on the server.
    
2.  Go to the **Network** tab.
    
3.  Click **Enable** next to the **Private network**.
    

![Image4](https://content.hostman.com/assets/a68b1d5c-d239-46d3-bdc8-2ca3f8bba991?width=1487&height=972)

3.  Select an existing network or click **Add Network** to create a new one.
    

-   **New network**: leave the default address range or specify your own. 
    

![Image2](https://content.hostman.com/assets/e9dd32d8-6f83-48ef-8926-f8c05026949c?width=1485&height=842)

-   -   **Existing network**: the server will be issued a private address automatically.
        

![Image14](https://content.hostman.com/assets/b8d25f5d-5192-4fa7-aaf1-69cc343c93d0?width=1489&height=845)

4.  Click **Connect**.
    

Hostman will start transferring the server to the private network. Usually it takes about one minute to transfer 10 GB. 

The server will be on during the transfer. After the transfer is completed, the server will be rebooted with the downtime of 5-10 minutes.

### When Creating a Service

1.  Start creating a new [cloud server](https://hostman.com/cloud-server/), database, load balancer or a Kubernetes cluster.
2.  In the **Network** step, select the private network from the drop-down list.

![Image11](https://content.hostman.com/assets/11120c26-2a80-4c99-9a7f-b312b953428c?width=779&height=500)

3.  Finish creating the service.

The service will be automatically added to this network when created. The private IP address for the service will be issued automatically.

## Removing Services from VPC

> [!NOTE]
> You can only remove **cloud servers** from VPC.
>
> Cloud databases or load balancers cannot be removed from VPC, but can be transferred to another private network.

To remove a server from a private network:

1.  Go to **Cloud Servers** and click on the server.
    
2.  In the **Network** tab, click **Configure** next to **Private network**.
    
3.  Click **Exclude from the network**.
    
4.  Click **Exclude and reboot**.
    

Hostman will start removing the server from this network. Usually it takes about one minute for each 10 GB of disk size.

After the process is completed, the server will be rebooted with downtime of 5-10 minutes. The network interface will be assigned a public IP address.

# Move Services Between VPCs

Source: https://hostman.com/docs/vpc/move-services/

You can move services between private networks within the same region.

> [!NOTE]
> -   For BGP networks, you will need to manually assign the private IP for the service after the migration.
> -   When moving a cloud server to another VPC, its public IP address may be changed.
> -   Kubernetes clusters cannot be migrated between any networks.

To move a service to another private network:

1.  Go to the page of the service.
    
2.  In the **Network** tab, click **Configure** next to **Private network**.
    
3.  Select an existing network or click **Add network** to create a new one.
    

Hostman will start transferring the service to the selected private network. Usually it takes about one minute to transfer 10 GB. 

The service will be on during the transfer and then rebooted when the transfer is completed. The total downtime will be about 5-10 minutes.

When moving services between BGP networks, you will need to assign a new private IP address:

-   for cloud servers, [follow this guide](https://hostman.com/docs/vpc/configure-private-ip/);
-   for cloud databases, load balancers, and Kubernetes, contact support.

# Configure Private IPs (BGP networks only)

Source: https://hostman.com/docs/vpc/configure-private-ip/

When working with BGP networks (private networks in Germany and the Netherlands), you may need to manually assign a private IP address to a server.

Depending on the operating system, you can do this using one of the instructions below.

In the examples, we configure the IP address `192.168.0.12/24`. Replace it with the address you need.

## Ubuntu, Debian 12

1.  Check the current network settings:
    

```shell
ip a
```

The following output indicates that no private IP address is assigned to the `eth1` interface (there is no `inet` field with a private address):

```yaml
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 54:52:00:f2:d0:09 brd ff:ff:ff:ff:ff:ff
    altname enp0s8
    altname ens8
    inet6 fe80::5652:ff:fef2:d009/64 scope link
        valid_lft forever preferred_lft forever
```

2.  Open or create a Netplan configuration file:
    

```shell
nano /etc/netplan/99-ipv4.yaml
```

3.  Add the following configuration:
    

```yaml
network:
  version: 2
  renderer: networkd
  ethernets:
    eth1:
      dhcp4: false
      addresses:
        - "192.168.0.12/24"
```

Here:

-   -   `eth1` is the interface name obtained from `ip a`.
    -   `192.168.0.12` is the private IP address you want to assign.

4.  Restrict permissions on this file so only `root` can read it:
    

```shell
chmod 600 /etc/netplan/99-ipv4.yaml
```

5.  Apply the Netplan configuration:
    

```shell
netplan apply
```

6.  After rebooting, the address may not yet be assigned by the time other services attempt to bind to it. To avoid issues, allow binding to non-local addresses. Open `/etc/sysctl.conf`:
    

```shell
nano /etc/sysctl.conf
```

7.  Add the following lines:
    

```shell
net.ipv4.ip_nonlocal_bind = 1
net.ipv6.ip_nonlocal_bind = 1
```

8.  Reload the `sysctl` configuration:
    

```shell
sysctl -p /etc/sysctl.conf
```

9.  Restart the networking service:
    

```shell
systemctl restart systemd-networkd
```

10.  Check the result:
     

```shell
ip a
```

If the private IP was successfully added, you will see a line with your address, for example:

```shell
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 54:52:00:c3:bb:ae brd ff:ff:ff:ff:ff:ff
    altname enp0s8
    altname ens8
    inet 192.168.0.12/24 brd 192.168.0.255 scope global eth1
        valid_lft forever preferred_lft forever
    inet6 fe80::5652:ff:fec3:bbae/64 scope link
        valid_lft forever preferred_lft forever
```

## Debian 11 and earlier

1.  Check the current network settings:
    

```shell
ip a
```

The following output indicates that no private IP address is assigned to `eth1`:

```shell
3: eth1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 54:52:00:f2:d0:09 brd ff:ff:ff:ff:ff:ff
    altname enp0s8
    altname ens8
    inet6 fe80::5652:ff:fef2:d009/64 scope link
        valid_lft forever preferred_lft forever
```

2.  Open the network interfaces configuration file:
    

```shell
nano /etc/network/interfaces
```

3.  Add the following lines:
    

```shell
auto eth1
allow-hotplug eth1
iface eth1 inet static
    address 192.168.0.12/24
```

Here:

-   -   `eth1` is the interface name obtained from `ip a.`
    -   `192.168.0.12` is the private IP you want to assign.

4.  Allow binding to the address. Open `/etc/sysctl.conf`:
    

```shell
nano /etc/sysctl.conf
```

5.  Add these lines:
    

```shell
net.ipv4.ip_nonlocal_bind = 1
net.ipv6.ip_nonlocal_bind = 1
```

6.  Reload the configuration:
    

```shell
sysctl -p /etc/sysctl.conf
```

7.  Restart the networking service:
    

```shell
systemctl restart networking.service
```

8.  Check the result:
    

```shell
ip a
```

You should now see your assigned IP address:

```shell
inet 192.168.0.12/24 brd 192.168.0.255 scope global eth1
```

## CentOS

1.  Check the current network settings:
    

```shell
ip a
```

The following output indicates that no private IP is assigned to `ens8`:

```shell
3: ens8: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP group default qlen 1000
    link/ether 54:52:00:43:ee:26 brd ff:ff:ff:ff:ff:ff
    altname enp0s8
    inet6 fe80::6f23:a5e7:7cb1:d9d9/64 scope link noprefixroute
        valid_lft forever preferred_lft forever
```

2.  Add a private IP address to the interface. First, check the connection name:
    

```shell
nmcli connection show
```

3.  Find the name assigned to `ens8` (in this example: `Wired connection 1`).
    

![Dbb822db 5ffa 4b62 A187 48e133b81b4d.png](https://content.hostman.com/assets/33d15a76-52f1-4d76-bde6-f72be7c450bc.png?width=769&height=58)

4.  Add the private IP to the connection:
    

```shell
nmcli connection modify 'Wired connection 1' ipv4.addresses 192.168.0.12/24
```

Here, `192.168.0.12` is the private IP you want to assign.

5.  Check that the IP was added:
    

```shell
nmcli connection show 'Wired connection 1' | grep addresses
```

6.  Disable old configurations. Check the directory:
    

```shell
ls /etc/sysconfig/network-scripts/
```

If there is a file named `ifcfg-ens8`, move it elsewhere to disable legacy settings:

```shell
mv /etc/sysconfig/network-scripts/ifcfg-ens8 /root/ifcfg-ens8-Backup-$(date +"%Y%m%d")
```

7.  Ensure the configuration persists after reboot by adding this linet to the `99-disable-network-config.cfg` file:
    

```shell
echo 'network: {config: disabled}' >> /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg
```

8.  Allow binding to the address. Open the config files:
    

```shell
vi /etc/sysctl.conf
```

9.  Add these lines:
    

```shell
net.ipv4.ip_nonlocal_bind = 1
net.ipv6.ip_nonlocal_bind = 1
```

10.  Reload the configuration:
     

```shell
sysctl -p /etc/sysctl.conf
```

11.  Restart NetworkManager:
     

```shell
systemctl restart NetworkManager.service
```

12.  Check the result:
     

```shell
ip a
```

You should now see your assigned IP:

```shell
inet 192.168.0.12/24 scope global ens8
```

# NAT

Source: https://hostman.com/docs/vpc/nat/

NAT is a network address translation mechanism that allows you to replace the private address of a service with a public IP when accessing the Internet.

> [!NOTE]
> NAT is available only in OVN networks, which are currently available in the USA.

Packets sent from services go through a traffic routing device. If the destination address is local, the packet is forwarded within the network to the local address. If the address is external, the router replaces the service’s private IP with the gateway’s public IP and sends the packet “outside”.

With NAT, you don’t have to issue unique public IPs to each service. Services within the private network that do not have their own public IP will access the Internet through the gateway IP address.

Public IPs are used as external IPs for NAT. If a public IP has not yet been assigned to the network, then when you enable NAT, you can select one of the existing public IPs on your account or create a new one. 

If at some point you no longer need to use NAT, the IP can be disconnected from the network and used for other services on the account or deleted.

## Enabling or Disabling NAT

### Enabling Manually

You can enable NAT manually in the settings of an existing network:

1.  Go to **Networks** → **Private Networks** and click on the VPC.
2.  Enable NAT.

![9d27823b 1199 494d B0df 92fa67689877](https://content.hostman.com/assets/7fec985d-a1ab-48ad-ba06-3e5a098fa27d.png?width=1534&height=845)

3.  If no public IP address is assigned to the private network yet, it will be assigned when you enable NAT.  You can choose one of the existing public IPs on your account or create a new one. 

![354dbb49 4fc5 472f 9a64 32f9ff1b2d51](https://content.hostman.com/assets/393757b8-39a7-466f-8439-0a7c9836d400.png?width=1533&height=841)

### Enabling Automatically

NAT will be **enabled automatically** when the “Outgoing Only” routing rule is enabled to any service in the private network.

### Disabling NAT

You can disable NAT manually in the settings of an existing network:

1.  Go to **Networks** → **Private Networks** and click on the VPC.
2.  Disable the **NAT** option.

**When disabling NAT:**

-   All services in the private network with the “Outgoing Only” traffic routing rule enabled will lose access to the Internet and will be available only within the private network. 
    
-   The public IP will be disconnected from the private network, but will remain on your account. When you re-enable NAT, you will be able to select the same IP if necessary. If a public IP is no longer needed, it can be linked to another service or deleted. 

## Traffic Routing Rules

The following traffic routing rules can be enabled for services: 

| Cloud servers | Incoming and outgoing Outgoing only Private network only |
| --- | --- |
| Cloud Databases | Incoming and outgoing Private network only |
| Load Balancers | Incoming and outgoing |

-   **Incoming and outgoing**
    

Incoming and outgoing traffic to/from the external network is allowed. The service has its own public IP for accessing the Internet.

If you disable the "Incoming and outgoing" rule, the service will lose its public IP address. When re-enabled, a new IP will be issued.

-   **Outgoing only**
    

Outgoing traffic to the external network is allowed, incoming traffic from the Internet is blocked. The service does not have its own public IP, it works behind NAT and can access the Internet with the gateway public IP.

When you enable the "Outgoing Only" rule for one of the services in a private network, NAT will be automatically enabled and a public IP issued for the gateway.

When NAT is disabled, all services with the "Outgoing Only" rule will lose access to the Internet and the rule will change to "Private network only".

-   **Private network only**
    

Only traffic within the private network is allowed, all external traffic is blocked. The service does not have its own public IP.

## Configuring Rules

You can configure traffic routing rules:

-   **In the private network settings**
    

Click on the traffic rule icon and select a new rule.

![Image8](https://content.hostman.com/assets/61a58b19-556e-4250-a01d-11116cb1e213?width=1333&height=866)

-   **In the service’s network settings**
    

Cloud servers:

1.  Go to **Cloud Servers** and click on the server.
    
2.  In the **Network** tab, click **Configure** next to **Traffic routing rules (NAT)**.
    

![Image6](https://content.hostman.com/assets/8e64522a-d3f2-455f-b4b3-58b98980a05b?width=1495&height=694)

3.  Select a new routing rule and save changes.
    

![Image12](https://content.hostman.com/assets/5a41270f-9803-4ac9-b380-c5143122dc4a?width=1490&height=763)

Databases:

1.  Go to **Databases** and click on the database.
2.  In the **Network** tab, enable or disable the **Allow access by public IP address** option. 

When enabled, the Incoming and outgoing traffic rule is applied. When disabled, the Private network only rule.

![Image1](https://content.hostman.com/assets/7ba26d49-2896-4fc2-b2d7-913c715f28be?width=1508&height=973)

## Service Cost

NAT is provided for free, however, it requires a public IP address, which is used as the public address for the private network. The cost of a public IP is $2 per month.

A public IP is charged as long as it exists on your Hostman account, even if NAT is already disabled. To stop the charges, delete the public IP from the **Networks** → **Public IP** section.

# Action History

Source: https://hostman.com/docs/vpc/history/

You can monitor the actions performed on private networks. To check the action history, go to **Networks** → **Private Networks** → click on the network → **History**.

![Image13](https://content.hostman.com/assets/cd663a56-4a8a-4ec5-bf5f-8bc0cc585ab1?width=1516&height=842)

Hostman logs the following operations:

-   Creating a VPC
    
-   Creating a service on the network
    
-   Transferring a service from a public or private network
    
-   Transferring a service to another private network
    
-   Excluding a service from the network

# Delete VPC

Source: https://hostman.com/docs/vpc/remove-vpc/

You can delete a private network that has no services in it. A network that contains any services cannot be removed. 

To delete a private network:

1.  Go to the **Networks** → **Private Networks** section.
    
2.  Click on the three dots next to the network.
    
3.  Click **Delete private network**. 
    
4.  Confirm the action.

# Public IP

Source: https://hostman.com/docs/public-ip/

A public IP is an external IPv4 address that you can transfer between services within the same region.

![F9830ec7 D710 4402 Afd5 0f56e94fc06b](https://content.hostman.com/assets/deb59002-d26e-4872-ae0b-d0ee5acf5dc1.png?width=1545&height=1013)

Assigning a public IP to a service allows it to access the Internet. 

When you assign a public IP to a VPC, it enables NAT allowing all services in the private network with a "Outgoing Only" routing rule to access the Internet through a shared IP address.

If you disable Internet access for a service, the public IP will be unlinked from it but retained on the account. You can reassign it to another service or the same one when you need to restore Internet access.

If you delete a service associated with a public IP, the IP address will still remain with your account, allowing you to transfer it to another service as needed.

You can request up to 10 public IP addresses per account per day.

> [!NOTE]
> Note that charges for an IP address will apply even if it is not linked to any service. To stop the charges, you must delete the IP address.

# Create a Public IP Address

Source: https://hostman.com/docs/public-ip/create-ip/

You can create a new public IP in the **Networks** → **Public IP** section or when creating a new cloud service on Hostman.

## Creating a New Public IP

1.  Go to **Networks** → **Public IP** and click **Add public IP**.
    
2.  Specify parameters:
    

-   **Region**: The public IP can only be assigned to services created in the same region.
    
-   **Number of addresses**: Select the number of IPs you need. You can order up to 10 addresses per day. You can always purchase additional addresses or release unused ones later.
    

4.  Click **Create**. 
    

![5e2aedf5 7d85 49ab Aef1 5d6791c41a53](https://content.hostman.com/assets/9f99bc04-2ad8-4fae-af9a-7f25f08ea7ec.png?width=1542&height=1163)

The IP addresses will be issued within a few minutes and will appear in the **Public IP** section. For convenience, you can filter them by region (availability zone).

![F88dc7d0 C48f 4cd0 B23a Dacd0f758e22](https://content.hostman.com/assets/8916d3db-ca45-44dd-ab76-8a755ab238e0.png?width=1545&height=1013)

You can now assign the addresses to the services.

## Creating a Public IP During Service Creation

You can also order a new public IP while creating a service.

During the creation process, in the **Network** section, select the **Public IP** option.

![069b5d25 5f25 4a61 9aed Feb679ea37d1](https://content.hostman.com/assets/e986cc3e-0d49-464d-84b6-69b79189f6ba.png?width=763&height=466)

In this case, the IP will be immediately linked to the service you are creating. Later, you can reassign it to another service within the same region.

# Assign a Public IP to a Service

Source: https://hostman.com/docs/public-ip/assign-ip/

You can assign a public IP to a cloud service as well as transfer an already assigned IP to another service within the same region.

## Assigning an Available IP to a Service

You can assign a new public IP to any service created in the same region / availability zone.

-   If the cloud server is configured to obtain an IP via DHCP (the default setting for our servers), you only need to assign the IP in the dashboard.
    
-   If you have manually changed these settings, you must add the IP inside the server using our [static IP configuration guide](https://hostman.com/docs/cloud-servers/administration/configure-static-ip/).
    

To assign a public IP to a service:

1.  Navigate to the **Networks** → **Public IP** section.
    
2.  Hover over the row with the IP address. A plus icon will appear on the right.
    

![Aaad46ae 0f4e 4c00 9de8 427325a92e24](https://content.hostman.com/assets/eddba48f-d253-4674-89ae-90f3f6266acf.png?width=1363&height=850)

3.  Choose a service:
    

-   If the service already exists, go to the **Existing** tab and select the service from the list.
    
-   If the service does not yet exist, click **New** and select the service type. You will be redirected to the service creation form with the required IP and region pre-filled. Complete the service creation process, and the public IP will be automatically assigned.
    

![52c2cb9c 8f05 4158 96fa 9ac90547a74c](https://content.hostman.com/assets/bbb2afdb-0f43-48b1-9545-7107c7e0d0ce.png?width=1522&height=820)

Assigning a public IP to a private network will enable NAT.

## Transferring a Public IP to Another Service

Public IPs can be transferred between services in the same region / availability zone.

To change an IP assignment:

1.  First, unassign the IP from the current service:
    
    -   Go to the **Networks** → **Public IP** section.
        
    -   Hover over the IP and click the minus icon.
        

![Edbf1223 33b4 4920 8448 119cd09793dd](https://content.hostman.com/assets/a7e91a6b-b6f5-4a7b-afdb-e04e08eaf4bc.png?width=1378&height=847)

-   -   Confirm the action in the next window.
        

> [!NOTE]
> **Note**: Unassigning a public IP will make the service inaccessible from the external network.

2.  Reassign the IP to a new service:
    
    -   Hover over the IP row again and click on the plus icon.
        

![Aaad46ae 0f4e 4c00 9de8 427325a92e24](https://content.hostman.com/assets/eddba48f-d253-4674-89ae-90f3f6266acf.png?width=1363&height=850)

-   -   In the popup window, select the service from the list or click **New** to create a new service and immediately assign the IP.
        

> [!NOTE]
> Assigning a public IP to a private network will enable NAT.

# Delete a Public IP

Source: https://hostman.com/docs/public-ip/delete-ip/

When deleting a public IP, keep in mind:

-   If the IP address is linked to a service, that service will lose its external IP and will no longer be accessible from the outside.
    
-   The same public IP cannot be recovered once deleted.
    

To delete a public IP:

1.  Navigate to the **Networks** → **Public IP** section.
    
2.  Click the three dots next to the address and select **Remove IP address**.
    

![A7270e73 Befd 4f8f A6df Cc4f56e9057b](https://content.hostman.com/assets/70c8322b-4e14-4b3d-ba44-8702ee038ef5.png?width=1372&height=868)

Or click on the address and use the delete icon in the top-right corner:

![76328a5e 0f7d 43e0 Aa66 B1b09c3ee7d9](https://content.hostman.com/assets/96d68500-ae6a-41ef-b94c-52fd1da936f7.png?width=1527&height=790)

3.  Confirm the deletion.

# Load Balancers

Source: https://hostman.com/docs/load-balancers/

Load balancers let you distribute incoming traffic across multiple servers to increase the availability and fault tolerance of your service.

The main benefits of load balancing are:

-   Horizontal scaling.
    
-   Load balancing for TCP sessions.
    
-   Support for HTTP, HTTP2, HTTPS, TCP ports.
    
-   Enhanced fault tolerance of your application server
    

WIth Hostman load balancers, you can balance traffic between both Hostman and third-party servers.

Once the balancer is set up, it will be assigned a public IP address. You will need to use this address as the application server address and redirect your domain name to it.

# Create Load Balancers

Source: https://hostman.com/docs/load-balancers/create/

To create a load balancer:

1.  Go to **Load Balancers** and click **Create Balancer**.
    
2.  Select region.
    
3.  Select configuration if available. The configuration with 2 nodes includes a replica of your load balancer to ensure fault tolerance.
    

![335a6d92 F38d 4b6c Bc14 69d97e71588f](https://content.hostman.com/assets/867180fd-9dbc-452c-b3cc-6a246e65138a.png?width=750&height=775)

4.  Select the maintenance window: a period during which system updates are allowed.
5.  Configure network settings: a public IP and a private network. For both, you can create a new one or select an existing one (should be created in the same region as the load balancer).
    

When creating a new network, you can set the IP address range for it.

| **Available ranges** | **Maximum CIDR size** | **Minimum CIDR size** |
| --- | --- | --- |
| 10.0.0.0/x | /8 | /28 |
| 192.168.0.0/x | /16 | /28 |
| 172.16.0.0/x | /12 | /28 |

6.  Specify basic settings for the load balancer.
    

-   -   **Add servers to the balancing**. You can add both Hostman and third-party servers. You can select a server from the drop-down list or enter an IP address.
        
        You will be able to add and remove servers later on, when the load balancer already exists.
        

-   -   **Set forwarding rules**. At least one forwarding rule must be specified. This will be enough to launch the load balancer.
        
        You need to specify the protocol and port for the server and for the balancer. Available protocols: HTTP, HTTP2, HTTPS, TCP. Each protocol will default to a standard port, but you can change this value to your liking.
        
        The specified parameters will be applied to all servers in the balancing.
        
        When setting up HTTPS, you must use TCP and port 443. If you are using Cloudflare, you must use only TCP as the source and destination protocols. Learn more about setup.
        

-   -   For additional configuration, click **Advanced settings**.

7.  Specify the name of the balancer and select which project it should be added to.
8.  Click **Create**.

You will be able to edit the list of servers, forwarding rules and advanced settings even after the load balance has been created.

# Manage Load Balancers

Source: https://hostman.com/docs/load-balancers/manage/

Manage your load balancers in the Hostman dashboard.

## Advanced Settings

To launch a load balancer, you only need to add servers and set at least one forwarding rule, leaving the rest of the settings as default. However, you can also configure the load balancing in more detail.

To configure a new load balancer, click **Advanced settings** in the **Settings** step when creating a load balancer.

To configure an existing load balancer:

1.  Go to the **Load balancers** section and click on the load balancer.
    
2.  Click **Configure** next to **Advanced settings**.
    

### Balancing Algorithm

Select your preferred balancing algorithm.

-   **Round Robin** sends requests to servers in turns: the first request to the first server, the next request to the second server, and so on until the last server, after which the cycle starts over.
    
-   **Least Connections** sends each new request to the server that currently has the least number of active connections. This method allows you to distribute the load on the servers fairly evenly.
    

### Sticky Sessions

When enabled, the load balancer uses cookies to redirect requests from the same client to the same server.

However, if the server becomes unavailable, the load balancer will redirect the client's request to another server.

### Health Checks

Health checks run in the background. The load balancer sends test requests to the servers. If a server fails the test, it is removed from the load balancing until it passes the test again. 

You can use default health checks parameters or configure them yourself.

First, set the basic parameters for sending test requests to the server: protocol and port. We recommend using the TCP protocol.

You can also set your own values for these parameters:

-   **Check interval**: how often to send test requests.
    
-   **Response timeout**: how long to wait for a response to a test request.
    
-   **Unhealthy threshold**: the number of failed tests in a row before the server is removed from balancing.
    
-   **Healthy threshold**: the number of successful tests in a row before the server is added back to balancing.
    

### SSL Certificate

When enabled, all HTTP traffic to the load balancer will be redirected to a secure connection. To make this work, you must create at least one rule to redirect from HTTP to HTTPS.

### Proxy Protocol

When enabled, the load balancer will pass client connection data (IP address and port) to the end server, rather than discarding it. This can be useful for collecting traffic statistics, showing a site or app in the user's language, or providing specific features based on the user's country.

The proxy protocol will work for all redirection rules with HTTP or HTTPS  as the target protocol.

Make sure the end servers support the Proxy protocol; otherwise, they will give a 400 error when health checked, and the load balancer will stop redirecting requests to them. 

Configuring your server to use the proxy protocol depends on the software you use:

-   [Nginx](https://docs.nginx.com/nginx/admin-guide/load-balancer/using-proxy-protocol/#configuring-nginx-to-accept-the-proxy-protocol)
    
-   [Apache](https://httpd.apache.org/docs/2.4/mod/mod_remoteip.html#remoteipproxyprotocol)
    

### Backend Keep-alive

When enabled, the load balancer will maintain persistent connections with the servers for all rules with HTTP or HTTPS as target protocol. This means that instead of opening and closing a new TCP connection for each request, the load balancer keeps the connection open for multiple requests.

In most cases, enabling this option will help improve performance and reduce response time for the client.

## Requirements and Limitations

When setting up redirects to HTTP and HTTPS, keep in mind the following details.

### Setting Up HTTP

If your redirect settings use the HTTP protocol, you may receive a 503 Service Unavailable error when accessing the domain.

To fix the problem, use the TCP protocol instead of HTTP in the health check settings:

![Image7](https://content.hostman.com/assets/26ffe594-7fc9-4976-847a-29f5f373c06e?width=606&height=164)

### Setting Up HTTPS

For HTTPS redirection to work correctly, you should use the following settings:

1.  In the forwarding rules, add a rule with TCP instead of HTTPS and use port 443, as shown below:
    

![Image8](https://content.hostman.com/assets/42b2076a-090f-4651-842b-82491108dde2?width=620&height=736)

2.  In the **Health checks** parameter, use the TCP protocol and port 80:
    

![Image7](https://content.hostman.com/assets/26ffe594-7fc9-4976-847a-29f5f373c06e?width=606&height=164)

3.  Set the load balancer IP address as the domain A record.
    
4.  Add an SSL certificate to each server’s domain in the balancing.
    

### Cloudflare Usage

If your domain uses Cloudflare name servers, you must choose TCP as the source and destination protocols when pointing the domain to the load balancer's IP address. Other protocols are not supported.

![Image8](https://content.hostman.com/assets/42b2076a-090f-4651-842b-82491108dde2?width=620&height=736)

### Port Restrictions

You cannot set up port 22 as the source port. If you try to connect to the load balancer on port 22, you will receive a _Connection refused_ error.

## Maintenance Window

A maintenance window is a period during which we may apply updates and optimize service performance.

Two options are available:

-   Anytime
-   At a specified time

The time is set according to your time zone.

You can set a maintenance window when creating a load balancer, and you can also manage it in the settings.

To change the maintenance window:

1.  In the **Load Balancers** section, click the load balancer you need.
    
2.  On the **Configuration** tab, click **Edit** in the **Load balancer m****aintenance window** block.
    
3.  Choose the desired option and save the changes.
    

## Domain Setup

Each load balancer is issued a public IP address. You can find the IP address in the **Load balancers** section.

![Image5](https://content.hostman.com/assets/bd4ef49f-eb7d-4594-94e1-b69973ad2e2d?width=1514&height=765)

Set this IP address as the A record of your domain.

## Action History

You can view the actions performed on load balancers. To check the action history, go to **Load balancers** → click on the load balancer → **History**.

We log the following events:

-   Creating a balancer
    
-   Adding a server to balancing
    
-   Removing a server from balancing
    
-   Creating forwarding rules
    
-   Changing forwarding rules
    
-   Changing load balancer settings

# Configure a Load Balancer With Terraform

Source: https://hostman.com/docs/load-balancers/how-to-add-a-load-balancer-rule-using-terraform/

Terraform is an infrastructure-as-code tool created by HashiCorp. It allows you to automate the creation and modification of infrastructure resources using the declarative configuration language HCL.

Terraform capabilities:

-   Managing infrastructure with a single tool
-   Version control and reusable configurations
-   Ability to track the current state of infrastructure

In this guide, we will look at how to manage load balancer rules using Terraform.

## Why Do You Need a Load Balancer?

A network load balancer allows you to evenly distribute incoming traffic across multiple servers to improve the availability and reliability of your service. It is an indispensable tool when implementing horizontal scaling of services.

Horizontal scaling is the process of adding additional nodes or machines to an existing infrastructure to increase its capacity and handle a larger volume of traffic.

Key benefits provided by a load balancer:

-   Load balancing for TCP sessions to ensure optimal server resource usage
-   Support for various protocols: HTTP, HTTP2, HTTPS, TCP
-   Application server fault tolerance to prevent service downtime and maintain availability
-   Ability to configure traffic routing rules to direct requests to specific server ports
-   Support for SSL configuration and redirection to HTTPS

## Creating a Network Load Balancer

First, we define the requirements for the load balancer:

-   We have two servers, each hosting a website on port 80
-   When accessing the load balancer on port 80, requests should be routed to one of our servers
-   Algorithm: Round Robin
-   No additional parameters

To add a rule to our load balancer, we need to create it and configure server load balancing. We added two servers to configure load balancing for them.

Next, we create a Terraform project. Check [this guide](https://hostman.com/docs/terraform/getting-started/) for more details on installing and configuring the provider.

First, create a folder where the configurations will be stored:

```shell
mkdir hostman-lb
cd hostman-lb
```

The file structure looks like this:

```shell
├── hostman-lb
│   ├── main.tf
│   ├── variables.tf
```

In the `variables.tf` file, we specify variables for the provider token and IP addresses for load balancing:

```shell
variable "hm_token" {
  type = string
  sensitive = true
}

variable "lb-ips" {
    type = set(string)
}
```

In the `main.tf` file, we add the provider information:

```shell
terraform {
  required_providers {
    hm = {
      source = "hostman-cloud/hostman"
    }
  }
  required_version = ">= 0.13"
}


provider "hm" {
  token = var.hm_token
}
```

When describing a Terraform configuration, we use two main types of entities: data sources (`data`) and resources.

-   Data sources are used to define variables and settings available within the chosen provider. Examples include presets, projects, and other parameters.
-   Resources are the infrastructure elements we want to create using Terraform, such as servers, databases, load balancers, and other components.

In `main.tf`, we specify a preset for configuration:

```shell
data "hm_lb_preset" "lb-preset" {
  requests_per_second = "10K"
  price_filter {
    from = 100
    to = 200
  }
}
```

If you use projects in the dashboard, you can specify the project where the resources will be created. For example, we add a project named "Docs":

```shell
data "hm_projects" "docs" {
  name = "Docs"
}
```

The resource we will create is called `hm_lb`. When creating it, you can specify many optional parameters, such as health check settings and load balancing algorithm. We'll take the simplest setup:

```shell
resource "hm_lb" "load-balancer" {
    name = "load-balancer"
    algo = "roundrobin"

    project_id = data.hm_projects.articles.id
    preset_id = data.hm_lb_preset.lb-preset.id

    health_check {
      proto = "tcp"
      port = 80
    }

    ips = var.lb-ips
}
```

Other parameters we can specify include:

-   `ips` — list of IP addresses for balancing
-   `is_keepalive` — flag indicating whether to maintain TCP connection with the server
-   `is_ssl` — automatic redirect to HTTPS
-   `is_sticky` — maintain user session on a single backend server

We also added a `.tfvars` file to the project with values for variables from `variables.tf`:

```shell
hm_token = "<insert API key for provider here>"
lb-ips = [ "<IP for first server>", "<IP for second server>" ]
```

Next, execute:

```shell
terraform validate
```

If everything is correct, you should see a success message.

To see which resources will be created, run:

```shell
terraform plan -var-file=.tfvars
```

The `-var-file=.tfvars` flag allows Terraform to use the variable values defined in that file.

Variables can also be defined in other ways:

-   Using the `-var` flag, e.g., `-var="hm_token=243453452345235456643"`
-   Using environment variables:

```shell
export TF_VAR_hm_token=243453452345235456643
```

## Adding Rules to the Load Balancer

A rule in the load balancer refers to port forwarding configuration. For any rule, you must specify:

-   The port clients access on the load balancer
-   The port on the target servers to which traffic will be forwarded

Add a new resource to the configuration in `main.tf`:

```shell
resource "hm_lb_rule" "lb-rule" {
  lb_id = resource.hm_lb.load-balancer.id
  balancer_proto = "http"
  balancer_port = 80
  server_proto = "http"
  server_port = 80
}
```

Run the commands again:

```shell
terraform validate
terraform plan -var-file=.tfvars
terraform apply -var-file=.tfvars
```

Confirm by typing `yes`.

In the dashboard, you will see the created resources:

-   Load Balancer
-   Rule

Visit the load balancer address (twice to reach different servers):

-   First server specified in variables
-   Second server specified in variables

If a second rule is needed, for example, a new application runs on port 81, simply add another resource block:

```shell
resource "hm_lb_rule" "lb-second-rule" {
  lb_id = resource.hm_lb.load-balancer.id
  balancer_proto = "http"
  balancer_port = 81
  server_proto = "http"
  server_port = 81
}
```

Run:

```shell
terraform plan -var-file=.tfvars
```

You will see that one load balancer and one rule already exist, and a new rule will be added.

Then run:

```shell
terraform apply -var-file=.tfvars
```

Agree to apply the configuration when prompted.

Check the dashboard—now two rules are configured. Visit the load balancer address to verify everything works correctly.

## Conclusion

In this guide, we learned how to create network load balancers and rules using Terraform. Besides Terraform, load balancers can also be managed via API.

Useful links:

-   [Hostman Terraform Provider Documentation](https://github.com/hostman-cloud/terraform-provider-hostman)
-   [Terraform CLI Documentation](https://developer.hashicorp.com/terraform/cli/run)
-   [Terraform Syntax](https://developer.hashicorp.com/terraform/language/syntax/configuration)

# Delete Load Balancers

Source: https://hostman.com/docs/load-balancers/delete/

When you delete a load balancer:

-   Traffic will no longer be redirected to the servers you added to load balancing. You will need to update the domains’ A records.
    
-   The servers will not be deleted.
    

To delete a load balancer:

1.  Go to **Load balancers** and click on the three dots next to the load balancer.
    
2.  Click **Delete load balancer** and confirm.
    

![062eb924 2ece 4660 Bf4a F9027a9cbcc8](https://content.hostman.com/assets/4ce31cfb-222c-4118-9968-44be20c73985.png?width=1573&height=774)

Alternatively:

1.  Go to **Load balancers** and click on the load balancer.
    
2.  Click on the bin icon in the top right corner and confirm.
    

![F8b70b48 Fbae 4d1a A7ff 59fc49ab6fef](https://content.hostman.com/assets/e642b788-acbf-4daf-a6e5-3ae3f60a15f8.png?width=1567&height=764)

# Firewall

Source: https://hostman.com/docs/firewall/

[Firewall as a service](https://hostman.com/cloud-firewall/) is a cloud solution that allows you to manage incoming and outgoing traffic from cloud servers and cloud services (databases, apps, balancers) using firewall rules you set.

You do not need to make any changes to the server settings at the operating system level. All you need to do is set the rules through your Hostman dashboard and select which servers and services they should apply to.

-   You can create up to 50 rule groups.
    
-   You can add up to 100 rules to a group for each type of traffic (incoming and outgoing).
    
-   You can include up to 200 services in a group.
    

A group of rules can be applied to any virtual servers, databases and balancers on the account, regardless of the region and availability zone where they were created.

### How It Works

When using a firewall, it is important to consider the following:

-   If no rules are created, the firewall is not applied and all traffic is allowed.
-   The firewall is applied separately to inbound and outbound traffic:
    -   If the group contains only inbound rules, filtering is applied to inbound traffic only.
    -   If it contains only outbound rules, filtering is applied to outbound traffic only.
    -   If it contains both inbound and outbound rules, filtering is applied in both directions.
-   A service can be included either in allowing traffic (whitelist) groups of rules or in prohibiting ones (blocklist).
    
-   A service can be added to two, three or more groups of rules of the same type (for example, to five groups of rules that allow traffic). In this case, all specified rules will be applied to the service.
    
-   Prohibiting rules work as a blacklist: only traffic specified by the rules is prohibited; all other traffic is allowed.
    
-   Allowing rules work as a whitelist: only traffic specified by the rules is allowed, all other traffic is denied. If, for example, you allow a rule for a specific TCP port, then traffic will be blocked not only to all other TCP ports, but also to all connections via other protocols.
    
-   Firewall rules only take effect for services in OVN-based private networks (San Jose and New York); they have no effect on services added to a BGP-based private network.

> [!NOTE]
> If you use an allowlist-based firewall, even a single rule for outbound traffic activates filtering. This means that anything not explicitly permitted will be blocked, including requests to websites, APIs, and other external services.
>
> We do not recommend creating allow rules for outbound traffic unless there is a specific need to restrict connections.

# Create Firewalls

Source: https://hostman.com/docs/firewall/create/

You can create a [cloud firewall](https://hostman.com/cloud-firewall/) from the Firewall section or from the settings of a particular service.

## In the Firewall Section

To create a firewall:

1.  Go to **Networks** → **Firewall** and click **Create**.
2.  Choose what this firewall needs to do: allow traffic or deny traffic.
3.  Set firewall rules for incoming and/or outgoing traffic. Later on, you will be able to edit the rules, delete them or add new rules.
4.  Select which services the rules should apply to. This setting can also be changed later on.
5.  Provide your firewall name if necessary and click **Create**.

## In the Service’s Network Settings

You can also create a firewall from the service's **Network** tab: scroll to the **Firewall** block and click **Configure**. A page for creating a new group of rules will open, where you can set rules, add services and save a new firewall.

# Configure Firewall Rules

Source: https://hostman.com/docs/firewall/configure-rules/

You can configure [cloud-managed firewall](https://hostman.com/cloud-firewall/) rules when creating a new firewall or when editing an existing firewall.

## Creating New Rules

> [!NOTE]
> If the **Allow traffic** option is selected, only traffic that matches the rule will be allowed. All other traffic will be blocked.
>
> If the **Deny traffic** option is selected, all traffic will be allowed except traffic specified by the rules.

### For a New Firewall

To create a new rule when creating a new firewall:

1.  Choose what you want to do: allow or deny certain traffic.
2.  Click **Add Rule** in the **Incoming Traffic** or **Outgoing Traffic** block. 
    

![93ed8f8f 85b8 418d Ae12 4c94f4205fd5](https://content.hostman.com/assets/0d31a731-3c74-4b88-bf4b-72ec1c7c866a.png?width=600&height=475)

3.  Specify the parameters:
    

-   -   **Subnet or address**. You can specify a specific IP, subnet, or the value `0.0.0.0/0` to allow/deny all addresses and subnets, or you can select **For all addresses**.
        
    -   **Type**. You can set your own rule or choose one of the ready-made types. In this case, the protocol and port will be filled in automatically.
        
    -   **Protocol**. You can select TCP, UDP or ICMP.
        
    -   **Port**. You can specify a port or a range of ports.
        

4.  Click **Add**.
    

### For An Existing Firewall

You can also add new rules to existing firewalls. To do this:

1.  Go to the **Networks** → **Firewall** section.
    
2.  Click on the firewall.
    
3.  Click **Add** in the **Incoming Traffic** or **Outgoing Traffic** block.
    

![3d2a760b A971 4733 B192 26d03f8fa491](https://content.hostman.com/assets/d5c11a84-6dec-4c1c-b35d-42ceb356beae.png?width=1555&height=827)

4.  Set the rule parameters and save the changes.
    

## Editing rules

To make changes to an already created rule:

1.  Go to the **Networks** → **Firewall** section.
    
2.  Click on the rule group.
    
3.  Click on the rule.
    
4.  Make your edits and save the changes.
    

## Deleting rules

To delete a rule:

1.  Go to the **Networks** → **Firewall** section.
    
2.  Click on the rule group.
    
3.  Click on the three dots next to the desired rule and click **Delete rule**.

# Configure Rules for Private Network Services (OVN only)

Source: https://hostman.com/docs/firewall/private-network-rules/

When configuring firewall rules for services in OVN networks (San Jose and New York), you must correctly set up the rules required for DHCP, which provides services with their private IP address. If this is not configured, the service may lose its IP address after the lease expires, which can cause NAT issues and make the service inaccessible from the internet.

> [!NOTE]
> This guide applies only to OVN networks (San Jose and New York). Firewall filtering isn't supported in BGP networks (Frankfurt and Amsterdam).

These settings are required if you have **allow rules** configured for services added to private networks. If rules are configured for both inbound and outbound traffic, you must apply both configurations.

## Rules Only for Inbound Traffic

If you have **rules created only for inbound traffic**, you need to allow inbound traffic to port 68/UDP from the gateway IP address of the private network where the service is located.

Example configuration:

![F725c24c 8a12 40cb 9e89 20731604f9d5](https://content.hostman.com/assets/8cbf9a17-ee54-4a00-a556-351e0efdbe22.png?width=482&height=863)

Replace `192.168.0.1` with the gateway address of your private network, or allow the entire private subnet (in this example `192.168.0.0/24`) or any addresses (`0.0.0.0/0`).

If services from different private networks with different gateway addresses are added to the same firewall group, you must create an allow rule for each gateway in the same way.

## Rules Only for Outbound Traffic

If rules are created **only for outbound traffic**, you need to allow outbound traffic to address `255.255.255.255` on port 67/UDP.

Example configuration:

![89517083 Cb33 4301 A024 De3fbdd11627](https://content.hostman.com/assets/a522251a-5361-45fd-a23e-ba5f8aa8f790.png?width=408&height=729)

Instead of `255.255.255.255`, you can also specify `0.0.0.0/0` to allow all addresses.

# Add Services to the Firewall

Source: https://hostman.com/docs/firewall/add-services/

You can add services to the firewall both when it is created and later, when the firewall already exists.

> [!NOTE]
> You can add a service to an allowing rule group only if it is not added to a prohibiting rule group, and vice versa.

A service can be simultaneously added to several groups of rules of the same type (allowing or denying).

## Add Services in the Firewall Section

When creating a [cloud firewall](https://hostman.com/cloud-firewall/): 

1.  Click **Select a service** in the **Connect to services** block.
2.  Select the ones you need.

When editing an existing firewall:

1.  Go to the **Networks** → **Firewall** section.
2.  Click on the rule group.
3.  Go to the **Servers** tab and click **Add**.
4.  In the window that opens, select the necessary services and save the changes.

## Add Services from the Service Page

You can add a service to the firewall from the service page itself. 

1.  Open the service in your dashboard and go to the **Network** tab.
2.  In the **Firewall** block, click **Configure**.
3.  Select the rule group and click **Save**.

## Delete Services from the Firewall

### In the Firewall Section

1.  Go to the **Networks** → **Firewall** section.
2.  Click on the rule group.
3.  Go to the **Services** tab.
4.  Click on the three dots next to the desired service and click **Exclude service from group**.
5.  Confirm deletion.

### In the Service's Network Settings

To exclude a service from the firewall:

1.  Go to the service's **Network** tab.
2.  In the **Firewall** block, click on the three dots next to the desired group of rules and click **Disable Firewall**.
3.  Confirm disabling the rule group for this service.

# Delete Firewalls

Source: https://hostman.com/docs/firewall/delete/

To permanently remove a [cloud-based firewall](https://hostman.com/cloud-firewall/):

1.  Go to the **Networks** → **Firewall** section.
    
2.  Click on the three dots next to the desired firewall.
    
3.  Click **Delete Rule Group**.
    

![333000ed 8bf0 4403 A451 E7774a812f00](https://content.hostman.com/assets/154a9f9a-05dc-4246-aa8d-c96badb457a0?width=1545&height=755)

4.  Confirm deletion.
    

The firewall and the rules created in it will be deleted and will no longer apply to the added services.

# Domains

Source: https://hostman.com/docs/domains/

You can add existing domains to your Hostman dashboard, host them on Hostman nameservers, and link them to Hostman services. 

> [!NOTE]
> At the moment it is not possible to buy domains via Hostman.

# Add Domains to Hostman

Source: https://hostman.com/docs/domains/add/

You can add your existing domains to Hostman, configure them to work with Hostman services and manage DNS records for the domains hosted on the Hostman nameservers.

## Step 1. Add Your Domain to Hostman

To add a domain to your Hostman dashboard:

1.  Go to **Domains and SSL** → **Add domain** section.
2.  Enter your domain
3.  Select a service it needs to be linked to. If you don't want to link the domain to a particular service, select **Do not link**.
4.  (Optional) Select the project to add the domain to.
5.  Click **Add**.

![43ee571b 519b 4c16 9531 7778539b8edb](https://content.hostman.com/assets/6e23336e-ea9a-47a1-ba4c-fa9f6e0b99f9.png?width=1365&height=792)

## Step 2. Configure Your Domain

For your domain to work with Hostman, you need to configure its DNS records: change the nameserves or the A record. 

To do it either, you will need to log in to your domain provider account. If you are not sure who your provider is, you can check it [here](https://lookup.icann.org/en).

### Option 1. Changing the A Record

To point your domain to a specific Hostman service, you can set the service's IP address as your domain's A record.

It is a quick and easy way to make your domain work with Hostman.

1.  Copy the IP address of the Hostman service you want to use the domain for.
2.  Log into your domain provider account.
3.  Find the DNS records settings.
4.  Set the IP address as the A record of your domain.

Propagation will take from 15 minutes to 3 hours.

The domain will work with the Hostman service, however you will still have to manage the domain’s DNS records in your domain provider account.

### Option 2. Changing Nameservers

Another way to point your domain to Hostman is by changing the nameservers it is hosted on.

Once your domain is pointed to Hostman nameservers, you will be able manage the DNS records in your Hostman account.

However, propagation in this case may take up to 24 hours, during which time your domain will be unavailable.

1.  Log into your domain provider account.
2.  Find the nameservers settings.
3.  Delete your current nameservers.
4.  Set the Hostman nameservers for your domain:

```shell
ns1.hostman.com
ns2.hostman.com
```

# Manage DNS Records

Source: https://hostman.com/docs/domains/manage-dns/

If your domain is pointed to the Hostman nameservers, you can manage the domain's DNS records in the Hostman dashboard.

## DNS Editor

To open the DNS editor:

1.  Go to the **Domains and SSL** section.
2.  Click on the cog icon.

![53c93db4 6819 4069 Afe3 45c822b72727](https://content.hostman.com/assets/792c981a-acea-460b-be49-d1746fda3e9c?width=1542&height=846)

Here you can manage the DNS records of your domain.

![A7ef7d9a Cf82 4ed6 8727 8cbe10bc50f0](https://content.hostman.com/assets/ba788cc1-52ce-4394-b674-d96bc934fb07.png?width=1570&height=840)

### Edit a DNS Record

To edit an existing record, click on it, make your changes, and save.

![7472119f 008c 4e89 Bfef 8795ce71dddb](https://content.hostman.com/assets/96c1d2c1-b50d-4945-b605-1c2c0fa44b1d.png?width=1567&height=838)

### Add a New DNS Record

To add a new record, click on **Add DNS record**, select the record type, add the values, and save.

![Ded67c43 C7ba 4465 856f 25cbf8a5a922](https://content.hostman.com/assets/4a397511-1cad-4193-9304-5f9c92d82089?width=1556&height=850)

### Delete a DNS Record

To delete a DNS record, click on three dots and click **Delete**. Confirm deleting the record.

![6103febf F98b 42d8 A344 66f40b6a895b](https://content.hostman.com/assets/a4bf931d-8232-4708-a6bb-746e561b75f3?width=1569&height=840)

## Usage Example

For example, to update the A record of your domain:

1.  Go to the **Domains and SSL** section.
2.  Click on the cog icon next to the domain.
3.  Find the A record in the list and click on it.
4.  Provide a new IP address for the A record by either selecting the service on your Hostman account or entering the required IP manually.

![Arecord](https://content.hostman.com/assets/466adffe-e3aa-453c-b76c-eb4d5376ab0c.png?width=1539&height=845)

5.  Click **Save**.

Usually, updating the A record will take up to 3 hours; in rare cases, in can be up to 24 hours.

# Import DNS Records

Source: https://hostman.com/docs/domains/import-dns/

If you have a zone file in the `.zone` format, you can quickly import all DNS records for a domain. This is convenient when migrating from another hosting provider or making bulk changes.

A `.zone` file is a regular text file that describes DNS records for a domain.

The `.zone` format allows you to define all required records in one place and upload them at once instead of entering them manually one by one.

## Supported Record Types

The following record types are supported:

-   A
-   AAAA
-   CNAME
-   MX
-   TXT
-   SRV

If the file contains other record types, they will be ignored. Such records will not appear in the list during import and will not cause an error.

From the directives used in `.zone` files, only the following are supported:

-   $ORIGIN: defines the base domain
-   $TTL: defines the default TTL

Other directives will be ignored during import.

## Import Records

To import DNS records:

1.  Go to the **Domains and SSL** section.
2.  Hover over the domain and click on the cog icon.
3.  Click **Import records**.

![46f09a07 532a 4ce0 B0c7 2c5341e32f9a](https://content.hostman.com/assets/516b089b-09da-4509-9a4d-2072b0226fa7.png?width=1572&height=836)

4.  Select a file with the `.zone` extension from your computer. 
5.  Check a preview list of all records that will be created. Records that contain errors will be highlighted.
6.  (Optional) Remove records you don’t need by clicking the **×** icon next to them.
7.  Click **Add X records** to save the changes.

![7eeb7be2 C527 4b57 8937 11dce8887f3b](https://content.hostman.com/assets/095882df-c903-44f3-8513-b678d1d972e4.png?width=1749&height=869)

# Manage Subdomains

Source: https://hostman.com/docs/domains/subdomains/

You can create subdomains for any existing domain added to your Hostman dashboard.

#### Keep in mind:

-   To set a TXT record for a subdomain (including SPF and DKIM), create this records for the main domain.
-   Subdomains use the same nameservers as the main domain.

> [!NOTE]
> Currently, it is not possible to change the nameservers for a subdomain. 

## Creating a Subdomain

To create a subdomain:

1.  Go to the **Domains and SSL** section and click on the domain.
    
2.  Move to the **Subdomains** tab and click **Create**.
    
3.  Specify the subdomain and the IP address to be used as the subdomain's A record. You can:

-   Choose one of the services on the account.
    
-   Manually enter an IP address.
    
-   Specify no IP address—in this case, an A record for the subdomain will not be created.
    

5.  Click **Add**.
    

![E661fcec 1bd0 4625 9d5a 9792d6b10c61](https://content.hostman.com/assets/07cf47b9-fb6f-48be-b4d8-2ed5cd97feeb?width=1571&height=844)

## Subdomain DNS Records

DNS records for a subdomain are managed exactly the same as for the main domain.

> [!NOTE]
> You cannot change the nameservers for a subdomain. The subdomain will use the same nameservers as the main domain.

To edit DNS records of a subdomain:

1.  Go to the **Domains and SSL** section and click on the main domain.
    
2.  Go to the **DNS** tab.
    
3.  Select the subdomain from the dropdown list.
    

![72d76b3e Dfc9 4aa3 955f E639181eb8e3](https://content.hostman.com/assets/88c040ab-fe9f-4365-bf7a-d3e0ca05e05c?width=1564&height=840)

You can edit existing records, delete them, and add new ones as described in the [Manage DNS Records](https://hostman.com/docs/domains/manage-dns/) article.

## Linking Subdomains to Services

You can change the service to which the subdomain is linked. This essentially means changing the A record for the subdomain. This can be done in two ways:

-   **In the DNS editor**: 
    
    1.  Go to the **Domains and SSL** section and click on the main domain.
        
    2.  Go to the **DNS** tab.
        
    3.  Select the subdomain from the dropdown list.
        
    4.  Edit the A record (or create one) and set the desired service or IP address as its value.
-   **Using the Change Server option**:
    
    1.  Go to the **Domains and SSL** section and click on the main domain.
    2.  Go to the **Subdomains** tab.
    3.  Click the three dots next to the subdomain and select **Change Server**.

![D60617d0 E428 4d6b Ad2c 3b903cc7baf3](https://content.hostman.com/assets/2dc6c6a2-0c6a-4542-87dd-391f9eb7ff0c?width=1574&height=842)

1.  4.  Select a Hostman service or manually enter an IP address you want to link the subdomain to.
        
    5.  Save the changes.
        

![6bec760a Da69 472f 89dc 438ee01e9609](https://content.hostman.com/assets/fc9efc6d-4fc3-4203-a669-b75f585aae34?width=1545&height=842)

## Deleting a Subdomain

To delete any subdomain:

1.  Go to the **Domains and SSL** section and click on the main domain.
    
2.  Go to the **Subdomains** tab.
    
3.  Click the three dots next to the subdomain and select **Delete subdomain**.
    
4.  Confirm deleting the subdomain.
    

![808661bc 8b13 4470 A3b3 2663130e6c54](https://content.hostman.com/assets/93ba2cae-ba22-4ac4-af6a-aa037fb23b59?width=1570&height=843)

# Move Domains Between Accounts

Source: https://hostman.com/docs/domains/move-between-accounts/

You can move domains between Hostman accounts yourself, following the steps below. All subdomains of the domain will be moved along with it.

1.  Go to the [Domains & SSL](https://hostman.com/my/domains) section.
    
2.  Click the three-dot menu next to the domain and select **Move domain**.
    

![Domains 2026 07 31 10 44](https://content.hostman.com/assets/59eac7ba-9295-465d-b202-629d54783d99.png?width=1574&height=833)

3.  Enter the login of the account you want to move the domain to.
    
4.  Click **Move**.
    

> [!NOTE]
> Sites linked to this domain or its subdomains, and hosted on servers in the current account, will **not** be transferred automatically. To migrate those sites, see our guide on migrating a project to a server.

# Manage DNS Records with Third-Party Providers

Source: https://hostman.com/docs/domains/dns-records-in-other-providers/

When you transfer your project to Hostman from another provider, move it to another server within Hostman, or change the server IP address, you need to make sure that your domain A record points to the server you need.

This should be done with your DNS hosting provider, basically, the owner of the nameservers the domain is hosted on. 

If your domain is using our nameservers:

```shell
ns1.hostman.com
ns2.hostman.com
```

— then you can change the A record and other DNS in the [Domains and SSL](https://my.hostman.com/domains/) section of your Hostman account, as described [here](https://hostman.com/docs/domains/manage-dns/).

If the domain has different nameservers and you are not sure who the DNS hosting provider is, contact your domain Registrar support. To get information about your domain, you can use [ICANN domain lookup](https://lookup.icann.org/en/lookup).

If you wish to edit DNS records through Hostman in the future, you need to set up Hostman nameservers listed above in your DNS hosting provider account.

In this guide, we will describe how to set up A record and nameservers in GoDaddy, one of the most popular domain registrars. 

With other providers the overall process will be similar: somewhere in the domain settings or DNS settings there will be the options to change the A record and nameservers. However, to get the exact instructions, please check links below or contact your domain provider support.

-   [Hostinger](https://support.hostinger.com/en/collections/2534491-dns-zone-management-at-hostinger)
-   [Dreamhost](https://help.dreamhost.com/hc/en-us/articles/360035516812-Adding-custom-DNS-records)
-   [Namecheap](https://www.namecheap.com/support/knowledgebase/article.aspx/767/10/how-to-change-dns-for-a-domain/)

## Setting Up A Record in GoDaddy

1.  Log in to your GoDaddy account and go to [Domain Portfolio](https://dcc.godaddy.com/control/portfolio).
2.  Click on the domain.
3.  Go to **DNS** → **DNS Records**.
4.  Find the A record with the name **@**.
5.  Click on the **Edit** icon on the right.
6.  In the **Value** box, enter the IP address of your Hostman server.
7.  Click **Save**.

Normally, updating the A record will take up to 3 hours; in rare cases, it can be up to 24-48 hours.

More details are available in the [GoDaddy Help Center](https://www.godaddy.com/help/edit-an-a-record-19239).

## Setting Up Nameservers in GoDaddy

If you want to manage your DNS records through Hostman in the future, you can set up our nameservers for your domain, following these steps.

1.  Log in to your GoDaddy account and go to [Domain Portfolio](https://dcc.godaddy.com/control/portfolio).
2.  Click on the domain.
3.  Go to **DNS** → **Nameservers**.
4.  Click **Change nameservers** and select the **I'll use my own nameservers** option.
5.  Add Hostman nameservers:

```shell
ns1.hostman.com
ns2.hostman.com
```

6.  Click **Save**.
    

Usually, the DNS propagation takes 24-48 hours.

More details are available in the [GoDaddy Help Center](https://www.godaddy.com/help/edit-my-domain-nameservers-664).