Docker Compose

Self-hosting with Docker Compose

Weavy provides a container image for use with Docker and other containerization tools. Here is an example compose file:

services:
  weavy:
    image: weavy/weavy
    restart: always
    depends_on:
      - db
    environment:
      - ASPNETCORE_HTTPS_PORTS=8081
      - ASPNETCORE_KESTREL__CERTIFICATES__DEFAULT__PATH=/https/weavy.pfx
      - ASPNETCORE_KESTREL__CERTIFICATES__DEFAULT__PASSWORD=weavy
      - CONNECTIONSTRINGS__WEAVY=host=db;database=weavy;username=weavy;password=weavy;gss encryption mode=disable;
      - WEAVY__LICENSE=YOUR-LICENSE-KEY
    ports:
      - 8080:8080
      - 8081:8081
    volumes:
      - ~/.aspnet/https:/https:ro
  db:
    image: postgres:18
    restart: always
    environment:
      - POSTGRES_USER=weavy
      - POSTGRES_DB=weavy
      - POSTGRES_PASSWORD=weavy
    volumes:
      - pgdata:/var/lib/postgresql/
volumes:
  pgdata:

Weavy is based on ASP.NET Core and requires HTTPS/TLS. For details on how to acquire and configure a certificate, see Hosting ASP.NET Core images with Docker Compose over HTTPS. In the example above, we assume you have a self-signed development certificates at ~/.aspnet/https/weavy.pfx with the password weavy, and ASPNETCORE_HTTPS_PORTS makes Weavy listen for HTTPS on port 8081.

Configuration

As seen above, environment variables are used to add and modify configuration values. Commonly used settings are:

Environment variable	Description
`CONNECTIONSTRINGS__WEAVY`	Connection string to the database (PostgreSQL 18 or later, or SQL Server 2022 or later with Full-Text Search).
`CONNECTIONSTRINGS__REDIS`	Redis connection string, used as realtime backplane when running more than one node. See Scaling out.
`WEAVY__APPLICATIONURL`	The public URL of Weavy, e.g. `https://weavy.example.com`. Recommended when Weavy runs behind a reverse proxy or load balancer.
`WEAVY__LICENSE`	Your license key. You can also install the license from the admin area at `/admin/license`.
`WEAVY__LOGLEVEL`	Minimum log level, e.g. `Debug`. Default is `Information`.

By default the image only listens for HTTP on port 8080. Set ASPNETCORE_HTTPS_PORTS and a certificate (as above) to also listen for HTTPS. If Weavy runs behind a reverse proxy that terminates TLS, HTTP on port 8080 is enough, but the proxy must send the X-Forwarded-Proto header.

Start Weavy

Start Weavy with docker compose up and open https://localhost:8081 in your browser. If everything worked out you should see the Weavy logo on your screen.

Without a valid license Weavy answers requests with 503 Service Unavailable instead of showing the logo. You can still create an admin account (see below) and install the license at /admin/license.

Create admin account

Next step is to create a local admin account for managing Weavy. Go to /admin/account and fill in the form to create an admin account and gain access to the /admin section where you can create API keys, view logs etc.

Health checks

The /live endpoint returns 200 OK as long as the process is running, and /ready returns 200 OK when Weavy can receive traffic and 503 Service Unavailable otherwise (e.g. when the database can't be reached). Without a valid license, or when the database must be upgraded, /ready returns 200 OK with the status degraded so that the admin area stays reachable, while other requests get 503 Service Unavailable. Use them as liveness and readiness probes in your container orchestrator. See Scaling out for details.

Scaling out

To run more than one Weavy container behind a load balancer, or to separate the admin area from the Web API, see Scaling out.

Troubleshooting

If the application does not start, or if you get an error on startup, the console should contain an error message describing the problem. A common problem is missing or invalid configuration settings. Once the database can be reached, the logs are also available in the admin area at Admin > Logs, and /ready tells you whether Weavy is ready to serve requests.