Services

Services represent components of your application like web apps, APIs, or workers. Each Service defines a project source (GitHub or a container registry) and manages the project's configuration. Koyeb uses these elements to build and run your code, ensuring that your application remains healthy and available. You can create up to 16 Services in each App.

Services are automatically versioned to provide full traceability. Each revision of a service is called a Deployment and is immutable.

Service types

Services are designed to run the various components of your stack. For each Service, you choose the type of process you require:

• Web Service: to run any HTTP, HTTP/2, WebSocket, or gRPC applications. You can choose to expose a Service in public (accessible through the internet) or in private (only accessible by other Services in your organization).
• Worker: to perform background tasks and asynchronous jobs. Workers are not exposed to the internet and private network but can access them. If you're not familiar with the concept of asynchronous processing, read our introduction to synchronous and asynchronous processing (opens in a new tab).

These different types of processes are all represented as Services.

Deployment methods

We provide two methods to deploy Services:

• GitHub: to trigger Deployments from a repository on GitHub. Using this deployment method, we pull down your codebase, build your project, deploy it, and keep it running for you. Git-driven deployments can automatically trigger redeployment whenever changes are pushed to their tracked branch. Read our documentation on how to deploy with GitHub for more details.
• Container images: to deploy your application using container images stored on any private or public registry. When you build your own Docker images, you control the complete execution environment of your App. Check the page on how to deploy pre-built Docker images for more details.

Service options

In addition to the Service type and Deployment method, you can configure the following:

• Instance type: to select the amount of resources for Instances of your application.
• Regions: to select the regions where your Services will run. End users will automatically be redirected by our Global Edge Network to the closest region where your Service is running.
• Volumes: to attach Volumes to your Services, enabling data persistence between Service deployments.
• Scaling: to define the number of simultaneous Instances running per region for your Service. This can be a static value or an autoscaling configuration.
• Environment variables: to configure environment variables required by your application during both build and execution. To securely store sensitive data, you can use Secrets as environment variable values.
• Exposed ports: to define the network ports where your Service should listen. All network ports are blocked by default and must be exposed explicitly. For public web Services, you must also provide the protocol and HTTP path that should be routed to the port.
• Health checks: to ensure maximum availability and determine your Deployment healthiness. You can define a health check for each port exposed by your Service.

Service statuses

All Services have statuses that indicate the health and life stage of the Service and its component parts. Additional messages are also available to help you understand the current state your resources and processes.

This section explains the different statuses you may encounter when creating and updating Services.

While reading this section, keep in mind that:

• Service statuses are based on Deployments statuses statuses, and
• Deployment statuses are based on the Deployment's Instance statuses.

Services can have several statuses during their life cycle:

• Starting: This is the initial state of a Service once the configuration is submitted and it's waiting to start.
• Healthy: The Service's desired number of instances are deployed and running. All defined health checks are responding. For web Services, all traffic is routed to healthy deployments.
• Degraded: The Deployment where the traffic is routed is degraded or the latest Deployment failed. This could be temporary, like with an Instance failure that will be automatically respawned, or you may have to fix something in your configuration, like increasing the Instance size your application keeps running out of memory.
• Unhealthy: No Deployment can serve requests.
• Deleting: The Service is being deleted.
• Pausing: The Service is being paused (someone triggered a pause on the service).
• Paused: All of the Service's Deployments are stopped. No traffic will be handled by the Service and no processing will occur.
• Resuming: The Service is being redeployed using the latest Deployment configuration. This happens when you resume a paused Service.