Deploy a Project Directory

Using the Koyeb CLI, you can build and deploy your application directly from your project's directory. Unlike deploying with GitHub or from a container registry, deploying from a project directory does not require any intermediary services.

How deploying a project directory works

The Koyeb CLI can bundle the contents of a directory and upload it to Koyeb using the koyeb archives create command. This creates a tarball (opens in a new tab) of the directory with a given name and uploads it to a store on Koyeb.

Koyeb deployment commands (like koyeb apps init, koyeb services create, and koyeb services update) can then use the archive as a deployment source by passing in the archive name with the --archive flag. This works in much the same way as deploying from a GitHub repository, replacing the git clone operation with one that downloads and unpacks the archive.

The koyeb deploy command simplifies this process by combining the archive creation and deployment steps into a single command. The command will bundle the contents of the given directory, upload the resulting archive to the Koyeb internal artifact store, and then build and deploy the application from the archive using a buildpack or Dockerfile builder.

Deploying a directory

To deploy a project directory, use the koyeb deploy command. At a minimum, this command requires a project path and a name for the App and Service you wish to create or deploy to.

For example, this command deploys the project in the current directory to an App called my-app and a Service called my-service:

koyeb deploy . my-app/my-service

This will archive the current directory and upload it to Koyeb's internal object store. It will then download, extract, and build the project the default buildpack builder.

You can check the Service status by typing:

koyeb service get my-app/my-service

ID      	APP   	NAME      	STATUS  	CREATED AT
1e24ec18	my-app	my-service	STARTING	08 Jun 24 13:04 UTC

To see the deployment logs, use the koyeb service logs command. By default, this shows the deploy logs. Pass in --type build to see the build logs:

koyeb service logs my-app/my-service

[2024-06-08 13:06:11 UTC] b19bb465  koyeb - Instance created. Preparing to start...
[2024-06-08 13:06:12 UTC] b19bb465  koyeb - Instance is starting. Propagating network configuration...
[2024-06-08 13:06:25 UTC] b19bb465  koyeb - Network configuration propagated
[2024-06-08 13:07:03 UTC] b19bb465 stdout -
[2024-06-08 13:07:03 UTC] b19bb465 stdout - > start
[2024-06-08 13:07:03 UTC] b19bb465 stdout - > tsx src/index.ts
[2024-06-08 13:07:03 UTC] b19bb465 stdout -
[2024-06-08 13:07:04 UTC] b19bb465 stdout - Server is running on port 8000
[2024-06-08 13:07:18 UTC] b19bb465  koyeb - Instance is healthy. All health checks are passing.

Customizing the deployment

You can customize how Koyeb builds and deploys your project by passing additional flags.

Most deployment flags are also applicable when deploying a project directory. The following options are especially useful for deploying project directories:

• --archive-builder: Whether to build using a native buildpack or from an included Dockerfile. Choices are buildpack and docker. Defaults to buildpack.

When using the buildpack builder, the following options are relevant:

• --archive-buildpack-build-command: When building with buildpacks, the command to run during the build of your application. For example: --archive-buildpack-build-command "yarn build".
• --archive-buildpack-run-command: When building with buildpacks, the command to run to launch the application deploying. For example: --archive-buildpack-run-command "yarn start".

When using the Dockerfile builder, these options are relevant:

• --archive-docker-dockerfile: When building from a Dockerfile, the location of the Dockerfile relative to the work directory. For example, --archive-docker-dockerfile "location/of/Dockerfile".
• --archive-docker-target: When building from a Dockerfile, sets the target build stage (opens in a new tab) to build within the Dockerfile. For example, --archive-docker-target builder.
• --archive-docker-command: When building from a Dockerfile, overrides the command (opens in a new tab) to execute at runtime. For example, --archive-docker-command "/bin/sh".
• --archive-docker-args: When building from a Dockerfile, sets the arguments to the command (opens in a new tab) to execute at runtime. Pass this flag multiple times to pass more than one argument. For example, --archive-docker-args "-g" --archive-docker-args "daemon off;".
• --archive-docker-entrypoint: When building from a Dockerfile, overrides the default entrypoint (opens in a new tab) for the container. For example, --archive-docker-entrypoint my-script.sh.

Other options that aren't specific to the project directory deployment method that you might want to adjust include:

• --type: The Service type, either "WEB" or "WORKER" (default "WEB")
• --instance-type: The instance type to deploy.
• --regions: The regions to deploy to.
• --env: An environment variable to set.
• --max-scale: The maximum scale to use.
• --min-scale: The minimum scale to use.
• --ports: The ports to expose for "WEB" Services.
• --routes: The paths to route for your "WEB" Service.
• --privileged: Chooses whether the Service container is run in privileged mode (opens in a new tab). This advanced feature is useful when you need elevated system privileges like, for example, to start a Docker daemon within the container.

Examples

The following command deploys the current directory and uses the Dockerfile builder. It passes the --verbose flag to the default command defined in the Dockerfile:

koyeb deploy . another-app/another-service --archive-builder docker --archive-docker-args "--verbose"

This command deploys the current directory, specifying the build and runtime commands:

koyeb deploy  . an-app/a-service \
              --archive-buildpack-build-command "pip install -r requirements.txt" \
              --archive-buildpack-run-command "python -m http.server"