Use Coolify to self-host SigNoz

Observability can be a tricky subject requiring a lot of dedication to do it properly. And one thing we don't want is to spend hours deploying the required services before even starting to integrate observability in our ecosystem.

Luckily for us, Coolify now have a template to easily deploy SigNoz, an open source observability platform. This guide will go through the steps to set it up in Coolify.

Adding the service

At the moment of writing, SigNoz' template is still in PR. To add it to your Coolify:

1. Copy the content of signoz.yaml from the PR.
2. In Coolify, create a new Docker Compose service and select the server to host it.
3. Paste the content of signoz.yaml in the "Docker Compose file" field.
4. Rename the service name to SigNoz.

URLs configuration

Once created, you are ready to set the URLs you'll use with SigNoz.

First, update the URL of the signoz container. For example: https://signoz.example.com:8080.

Then, let's configure the Otel Collector. This service collects the traces, metrics and logs from your applications and services and supports many different formats: OTel' GRPC and HTTP formats, Prometheus metrics, and many logs formats (FluentBit/FluentD, syslogs, logs from cloud services, ...).

Each format should be received on a different port, which we will need to expose for the OTel Coollector to be accessible. You have two strategies to do so:

• Configuring a domain for each receiver, or...
• Directly exposing the ports to the host and the outside world.

Which option you prefers depends on you security needs and how you architecture your domains.

One subdomain per receiver

This solution only requires you to map your subdomain to the Otel Collector service. We will cover the two default receivers, the HTTP and GRPC receivers.

1. Make sure your subdomains have been registered and point to your server. In my case, I chose https://signoz-grpc.example.com and https://signoz-http.example.com.
2. Open the "Otel Collector" service settings.
3. Add your domains with the format https://<subdomain>.example.com:<port in container>, separated by commas.

For example, this is what I have setup:

https://signoz-grpc.example.com:4317,https://signoz-http.example.com:4318

If you want to drain logs from Heroku, you can add a subdomain to receive the logs: ...,https://signoz-heroku.example.com:8081.

Exposing the ports on the host

If you prefer to use a single domain for all receivers, you can edit the Docker Compose to directly expose the ports on the otel-collector container:

services:
  # ...
otel-collector:
  image: signoz/signoz-otel-collector:latest
  container_name: signoz-otel-collector
  # ...
  ports:
  - 4317:4317 # GRPC Collector
  - 4318:4318 # HTTP Collector

  # ...

You can now append the port to your service URL to send data to receiver: https://signoz.example.com:4318

Fixing the health checks

If you tried to run the services, you should have noticed Coolify keeps reporting SigNoz as unhealthy. This is because some containers exit after performing their task, causing Coolify to consider them unhealthy.

To have Coolify properly reporting the health status, you will need to exclude Schema Migrator Sync, Schema Migrator Async and Init Clickhouse from the healthcheck.

1. Open the settings of the service.
2. Check Exclude from service status and save the settings.
3. When you excluded the three services, you can now (re)deploy all SigNoz services for the health check to ignore these three containers.

Enabling SMTP emailing

SigNoz uses emailing for two things: inviting users and to send alerts.

SigNoz emails

To enable SMTP emailing (including inviting new team members), you need to set the following variables from the Environment Variables tab of your Coolify service:

• SIGNOZ_EMAILING_ENABLED enables emailing capabilities in SigNoz.
• SIGNOZ_EMAILING_SMTP_ADDRESS is the address of the SMTP server to use, in the format host:port.
• SIGNOZ_EMAILING_SMTP_FROM is the email address to use in the From field.
• SIGNOZ_EMAILING_SMTP_AUTH_USERNAME and SIGNOZ_EMAILING_SMTP_AUTH_PASSWORD are used to authenticate with the SMTP server.

More environment variables are available to use to use authenticate via Identity / Secret or use TLS instead of SmartTLS. Read Passing environment variables not included in the template to learn how to add them.

Alert Manager emails

Email alerts can only be sent if an SMTP server is configured specifically for the alert manager. The global SMTP configuration and the Alert Manager configuration use different environment variables.

Note: SigNoz has a current known issue preventing email alerting configuration from being saved. You can track the progress of this issue in their bug tracker.

To enable email alerts, you need to set the following variables from the Environment Variables tab of your Coolify service:

• SIGNOZ_ALERTMANAGER_SIGNOZ_GLOBAL_SMTP__SMARTHOST is the address of the SMTP server to use, in the format host:port.
• SIGNOZ_ALERTMANAGER_SIGNOZ_GLOBAL_SMTP__FROM is the email address to use in the From field.
• SIGNOZ_ALERTMANAGER_SIGNOZ_GLOBAL_SMTP__AUTH__USERNAME and SIGNOZ_ALERTMANAGER_SIGNOZ_GLOBAL_SMTP__AUTH__PASSWORD are used to authenticate with the SMTP server.

More environment variables are available to use to use authenticate via Identity / Secret or use TLS instead of SmartTLS. Read Passing environment variables not included in the template to learn how to add them.

Passing environment variables not included in the template

You may want to define environment variables that are not included in SigNoz' template (for example new TLS settings for the SMTP / Alert Manager email configuration). Luckily, Coolify makes this process pretty simple:

1. Edit the Docker Compose in Coolify.
2. Add the desired variables to the environment of the signoz container with the following format: - <VARIABLE_NAME>=${<VARIABLE_NAME>}. For example: SIGNOZ_EMAILING_SMTP_FROM=${SIGNOZ_EMAILING_SMTP_FROM}.
3. Go in the Environment Variables tab of you Coolify service and set the value of the newly added variables.

Updating SigNoz

To update SigNoz to a more recent version, you just need to pull the latest version in Coolify.

1. Open the service in Coolify
2. Top right of the screen, click on "Advanced" and select "Pull Latest Images and Restart".
3. Wait for the migration and full restart of SigNoz (can take a few minutes).

Conclusion

SigNoz is now setup and ready to accept logs and traces from your applications and infrastructure.

Their documentation is a good start to learn how to onboard your resources. OpenTelemetry documentation is also a reference, containing the recommended steps to best leverage the OpenTelemetry SDKs and tools for your stack.

Did you find any way to improve the Coolify template, SigNoz setup, or want to suggest a change? Feel free to let me know! I'd be very happy to learn how to make SigNoz even more pleasant to use.