Deploying a Service

A service in Sliplane is a container with specific configuration. A service might be a website, a backend API, a recurring job, a database or anything else you want to run on your server.

To create a new service, select a project first and then click Deploy Service at the top right corner of the page.

Deploy to Server

At the beginning, you need to select a server, where the service should be deployed to. If you have not done so already, create a server first, where you can deploy your service to.

Each server can run multiple services.

Deploy source

You can either deploy from a GitHub repository or deploy from a registry. We currently support GitHub Container Registry (GHCR) and Docker Hub as registry providers.

Additionaly we provide the option to deploy some pre configured public images from Docker Hub. These include PostgreSQL, MongoDB, MySQL, MariaDB and more. Under the hood, it's the same thing like deploying a public image from Docker Hub, but we already prefill all the necessary configuration to get the image up and running with just a single click.

Deploy from GitHub

You can deploy services, simply by selecting a repository, that contains a Dockerfile with build instructions.

Note: Docker compose files do not work yet. For now, you'd have to spin up each service individually.

Sliplane will do the following:

Pull the latest state of your codebase
Look for a Dockerfile in your repository and build a Docker image based on the instructions inside the Dockerfile and additional configuration that you provide through our platform
Start a container from the image and if specified, expose your service
Validate that the container is running
Redirect traffic to the new container

To get started, select GitHub as a deploy source in the deploy form. This setting is usually preselected by default.

Select a Repository

Next, choose the repository from the dropdown menu, that you want to deploy. Take note that you have to allow Sliplane to access the repository in your GitHub account first. In the "Select a Repository" dropdown, click "Configure Repository Access".

This will redirect you to your GitHub Account, where you can manage Sliplanes access to your repositories.

You can read more about what Sliplane is doing in the GitHub chapter.

Note: It might take a minute after you saved your settings in GitHub, until the repository will show up in Sliplane. Hit the "Refresh List" button at the end of the dropdown, to check if the repository became available.

Select a Deploy Branch

Select the branch of your repository that should be deployed. By default new commits on this branch will be deployed automatically. After your first deploy, this setting can be changed in your services settings by disabling the "Automatically deploy new commits" toggle.

Dockerfile Path

The Dockerfile path specifies the path to a Dockerfile inside your repository, that should be used to build your Docker image. You can only deploy a repository that contains a valid Dockerfile with build instructions for your image.

Sliplane will try to find this Dockerfile in your repository and prefill this setting for you. However, if you renamed your Dockerfile or you are using a monorepo with multiple Dockerfiles this initial guess might be wrong and you'll have to update the setting here.

Make sure to always end the path with the filename e.g. /app/Dockerfile

Docker context

This option defines a directory of your repository that serves as the root for all commands in your Dockerfile. The default / points to your repository root.

Say your Dockerfile contains a COPY . . instruction. This command will copy everything from the root directory of your repo to your image. But what if your repository contains multiple folders, with multiple Dockerfiles in it and each Dockerfile should only copy the contents of its parent folder?

In that case you would specify the Docker context to point to the folder containing the Dockerfile. A COPY . . instruction will then only copy the contents of that folder.

Deploy from a Registry

You can also deploy container images from a container registry. We currently support GitHub Container Registry and Docker Hub.

Sliplane will do the following:

Pull your image from the registry
Start a container from the image with the config you provide through Sliplane
Validate that the container is running
Redirect traffic to the new container

In the deploy form, select "Registry" as a deploy source up top.

Image URL

The URL pointing to the image in your registry. Make sure to stick to the following format:

On Docker Hub :

docker.io/namespace/image-name:tag

On GitHub Container registry:

ghcr.io/namespace/image-name:tag

Examples:

docker.io/grafana/grafana:9.5.20 docker.io/library/postgres:16.2 ghcr.io/sliplane/file-upload:latest

Make sure to enter the URL without the networking protocol (no http or https).

If the namespace for an official public image on Docker Hub is not explicitly specified, it becomes "library".

Alternatively you can search for a public image on Docker Hub. Click on "Search Docker Hub" and type the name of your image inside the "Image Name" input. Make sure to type the image name exactly as it is, or otherwise it can't be found.

Select the version of your image by choosing a tag from the "Image Tag" dropdown. By default the 'latest' tag will be selected.

Note: The "Latest" tag setting is not recommended in a production setting. A redeploy will always download the newest version of this image which can lead to unintended upgrades of new code that has not yet been tested agains other parts of your application. So in production applications better choose an explicit tag.

Credentials

If your image is private you can access it by providing an authorized credential or in other words your username and password or access token.

In Sliplane, your credentials are stored on team level, meaning everyone in the team can use them.

Choose a credential from the dropdown or add a new one if you need to.

You can read more about registry credentials in the teams section.

Expose Service

If your service should be reachable over the internet, activate this toggle. This applies to websites for example or public APIs.

In case your service does not need to communicate with the outside world, you can turn of that switch for an additional layer of security. In that case, only services that are running on the same server can communicate with your service. This setting can be useful for running a private database for example, that should only be accessible from your backend on the same machine.

You can reach private services on the same server through the internal host domain that you can find in the service settings.

Note This setting can not be changed later on!

Networking protocol

Select the networking protocol for your service. Most of the services, that get deployed via Sliplane, are communicating via "TCP/HTTP". This is the default setting. However, some applications use more low level protocols to communicate like "TCP" or "UDP". Databases for example are usually not accessible via HTTP, so you need to change the protocol there.

Health check route

For HTTP services, you can specify a health check route. This route will be used to validate, that deploys have been successfull and to regularly check, if your service is still running.

For example, if you add /, we will check at http://localhost:PORT/. If you add /health, we will check at http://localhost:PORT/health. If you don't add a health check, we will use / as default.

It's important that a GET request on the health check route of your app returns a 2XX status code and no authentication is required, otherwise deploys will fail.

Sliplane will hit this route after each deploy and only redirect traffic to the new version of your service, once health checks are green.

Healtch checks are also performed in 1 minute intervals to check whether your app is still running. If they fail 3x in a row, you will get notified via email.

Environment Variables

Environment variables are a great way to configure your service and keep secrets out of your code. For example, you might want to add a DATABASE_URL environment variable that contains the connection string to your database or a BASE_URL that specifies the domain your service is currently running on.

Sliplane supports environment variables out of the box. These environment variables are available to your service as process environment variables (during build and runtime!) and if no .env file exists in the root of the project (it shouldn't!), Sliplane will create one for you with the environment variables you have configured. The .env has the following format:

KEY1=VALUE1
KEY2=VALUE2
...

You can either set environment variables as key-value pairs, or paste the content of your .env file.

NOTE: Do not use localhost in your environment variables, since this won't work with Docker. Instead, use 0.0.0.0.

Volumes

Containers are ephemeral. This means, that they get spun up and destroyed quite frequently, and when that happens all data inside is deleted as well. For that reason, it is not recommended to store any data inside a container, that should persist.

If your application relies on data that needs to persist between deploys you can attach a volume to your service.

Simply speaking, a volume mirrors a folder inside your container and stores it on the host system. That way, when the container is teared down, the folder still persists and you can keep all data inside it.

To mount a volume to your service, you need to specify the mount path, pointing to a folder inside your service that should persist.

Note: The mount path is the absolute path from your container root. If your app inside the container is running in a workdir you also have to include it in your mount path.

Reserved keys

Certain keys are used internally by the Sliplane client and can not be overwritten by you. The keys and explanation can be found in the following list:

PORT: The PORT variable is used by the Sliplane to tell your service on which port to listen. It should be in the range of 8080 to 65535. If your service is exposed to the internet via HTTP and fails to listen to the specified port the deployment and healthchecks will fail.

Service Name

Enter a name for your service. The default is your repository name. Your subdomain will be your-service-name.sliplane.app if available.

What happens if a new deploy fails?

If you push code and the build or start command fails, we will not redirect the traffic to the new version of your application. Instead, we will keep the previous version of your application online. This way, your users will not experience any downtime. You will also be able to see the logs of the failed deploy in the logs section of your service!

If you have any questions or need assistance in setting up your service, please do not hesitate to contact us. We're always here to help!