Skip to main content

Getting started

Deploy your first containerized application on Vicugna.

Before you begin​

You need:

  • A Vicugna account
  • A Docker image that listens for HTTP traffic
  • The port that the application listens on inside its container

For a quick test, use nginx:latest, which listens on port 80.

Create a project​

After signing in, create a project and give it a name. A project groups the services that you deploy together.

Create your first service​

Open the project and choose New service. Fill in the service form:

  • Hostname: a unique lowercase name for the service, such as web or api. It may contain letters, numbers, and hyphens, must start with a letter, and must end with a letter or number.
  • Docker image: the image reference, such as nginx:latest or ghcr.io/your-user/myapp:latest.
  • HTTP port: the port exposed by the container, such as 80 for Nginx or 3000 for many web applications.

The port is the port inside the container. You do not need to expose or publish it with Docker flags.

Click Create service. Vicugna schedules the deployment and shows its current status. Once the service is running, open its detail page to inspect the image, port, hostname, and deployment status.

Services in the same project share an internal network. They can communicate with each other using the other service's hostname, without a public URL. For example, an application in web can connect to a database or API at db or api on the port that service listens on.

Make the service public​

Services are private by default. From the service detail page, choose Generate subdomain to create a public HTTPS address. Vicugna will display the generated URL when it is ready.

If you do not generate a subdomain, the service remains available only inside its project network.

Add persistent storage​

Enable Persistent storage when the service needs data to survive restarts. By default, Vicugna mounts the volume at /data; set a different absolute mount path if your application writes elsewhere.

Persistent storage is suitable for application data, but it is not a replacement for backups.

Configure secrets​

When creating a service, add environment secrets such as database URLs or API keys. Secret names must start with a letter or underscore and contain only letters, numbers, and underscores. Values are injected into the service without being included in the image reference.

Deploy a private GHCR image​

For a private ghcr.io image, expand Optional private GHCR credentials and provide a GitHub username and a classic personal access token with the read:packages scope. Provide both credentials; they are used by Vicugna to pull the image.

Troubleshooting​

If the service does not become healthy, first check that:

  1. The image reference is valid and available to Vicugna.
  2. The HTTP port matches the port the application actually listens on.
  3. The application binds to 0.0.0.0, not only to localhost inside the container.
  4. Private GHCR credentials have the read:packages scope and match the image owner.