Getting Started with Docker
Seq is available on Docker as datalust/seq
. Seq's Linux-based Docker image is ideal for deployment to Linux hosts and container orchestrators, and for for local development on Linux or macOS. It also has a Helm chart for simplifying Kubernetes deployments.
Seq is distributed as an officially supported datalust/seq
container image on Docker Hub.
Kubernetes support
Seq has a Helm chart for simplifying deployments in Kubernetes. See the Kubernetes deployment docs for more details.
Running Seq in a Docker container
PH=$(echo '<password>' | docker run --rm -i datalust/seq config hash)
mkdir -p <local path to store data>
docker run \
--name seq \
-d \
--restart unless-stopped \
-e ACCEPT_EULA=Y \
-e SEQ_FIRSTRUN_ADMINPASSWORDHASH="$PH" \
-v <local path to store data>:/data \
-p 80:80 \
-p 5341:5341 \
datalust/seq
This will start a Seq instance with:
--name seq
to be able to run commands using the container name, e.g.docker stop seq
-d
run in daemon mode (in the background), omit this argument to see container logs instdout
--restart unless-stopped
always restart the Seq docker container if it stops, except when you rundocker stop seq
-e ACCEPT_EULA=Y
to run Seq, you must accept the End User License Agreement-e SEQ_FIRSTRUN_ADMINPASSWORDHASH="$PH"
to set an initial password for theadmin
user account; replace<password>
with your desired password; the first line above stores a cryptographic hash of the password into the environment variable$PH
(bash syntax)-v <local path to store data>:/data
mounts<local path to store data>
on the host machine to/data
on the docker container - this is where Seq stores all its configuration and log files. Storing Seq data outside of the container means that Seq's log data and metadata persist beyond the life of the container, and don't increase the size of the docker container.-p 80:80
map the host'slocalhost:80
to Seq UI and API (port 80)-p 5341:5341
map the host'slocalhost:5341
to Seq's special ingestion-only port (port 5341). We recommend exposing the ingestion-only port separately.
The container can be stopped and started using the docker stop seq
and docker start seq
commands, respectively.
After running the command above, browse the Seq UI at http://localhost:80.
Memory limits
For Seq to accurately measure available memory, depending on the hosting infrastructure, it's often necessary to specify memory limits for the container. If the Seq container exits unexpectedly, or fails with out-of-memory errors, specify the --memory
and --memory-swap
arguments to docker run
:
docker run --memory=16g --memory-swap=16g <other args> datalust/seq
The argument to these flags is the total memory that the system should provide for the container (more is better). Normally, both flags should have the same value, effectively disabling swap for the container.
If you're running Seq on a local machine with a fast disk, or in a memory constrained (500MB or less) environment, you can configure Seq to run without a cache:
docker run --memory=500mb --memory-swap=500mb -e SEQ_CACHE_SYSTEMRAMTARGET=0 <other args> datalust/seq
This will instead use a much smaller native cache that only covers very recently ingested data. Other events will be fetched from disk on-demand.
Persistent volumes
The Seq Docker container stores configuration and log events in its /data
directory. For this directory to survive container restarts, it needs to be mapped to a persistent volume using -v
on the command-line, as in the example above.
Seq is a database; the volume provided to it should be equivalent to local disk storage, for example an Azure Disks VHD or an AWS EBS volume.
Only one running Seq container can access a storage volume concurrently: it's not possible to run two or more container instances pointing to the same storage.
Azure Files volumes
When running Seq on Microsoft Azure, only Azure Disks volumes (mounted VHDs) are recommended for persistent storage.
Azure Premium Files is not compatible with Seq.
Enabling authentication
If you specified an initial password for the admin account on the docker run
command-line, authentication will already be enabled.
If not, your next step should be visiting Settings > Users and enabling authentication.
Ingesting log events
Using logging libraries
Before you can benefit from Seq, your applications need to be configured to send log events through one of the supported logging libraries.
- Using Serilog - Serilog is a modern logging library for the .NET platform with deep support for structured event data.
- Using ASP.NET Core - the Microsoft.Extensions.Logging library included in ASP.NET Core works well with Seq.
- Using Node.js - on Node.js, we support the Pino, Winston, and Bunyan logging libraries.
Seq integrates with a range of languages, libraries and frameworks, and has a simple HTTP API for receiving log data. Learn more about getting logs into Seq.
If you're unsure where to start, we recommend Serilog.
Using CLI or HTTP
Your applications can also log events to Seq by tailing their output with the seqcli
command-line client
./my-app | seqcli ingest
or posting JSON directly to Seq:
curl -XPOST "http://your-seq-host/api/events/raw?clef" \
-d "{'@t':'2018-06-07T03:44:57.8532799Z','@mt':'Hello, {User}','User':'alice'}"
Containerized services can also forward their logs to Seq natively using Docker's GELF (Graylog extended log format) log driver.
Changing the default ingestion port
Containers can expose the limited ingestion port in addition to, or instead of, the API port. In the container the ingestion port is mapped to 5341
:
docker run \
-e ACCEPT_EULA=Y \
-v $HOST_PATH_TO_SEQ:/data \
-p $HOST_HTTP_PORT:80 \
-p $HOST_INGESTION_PORT:5341 \
datalust/seq:latest
where:
$HOST_PATH_TO_SEQ
is an absolute path on the container host for the Seq instance to use.$HOST_INGESTION_PORT
is a port on the host to expose the Seq ingestion endpoint on.
Running other Seq commands in a docker container
Any arguments specified after the datalust/seq:latest
image in the docker run
command will be passed as arguments to the Seq binary:
docker run \
--rm \
-e ACCEPT_EULA=Y \
-v $HOST_PATH_TO_SEQ:/data \
datalust/seq:latest version
where:
$HOST_PATH_TO_SEQ
is an absolute path on the container host for the Seq instance to use.
Container environment
File paths
Important file paths used by Seq in the container.
Value | Description |
---|---|
/data | Location of Seq extents and logs |
Ports
Important ports used by Seq in the container.
Value | Description |
---|---|
:80 | The port that Seq binds to the API and UI |
:5341 | The port that Seq binds to the ingestion-only endpoint |
Environment variables
Environment variables used by Seq in the container. For a full list of environment variables supported by the container, see the Server Configuration reference.
Value | Description |
---|---|
ACCEPT_EULA | Must be set to Y to indicate acceptance of the Seq EULA |
SEQ_API_CANONICALURI | The external URI that can be used to reach Seq outside of the container |
SEQ_FIRSTRUN_ADMINUSERNAME | A username for the default administrator account, used only when the container is first initialized; the default is admin |
SEQ_FIRSTRUN_ADMINPASSWORDHASH | A salted, cryptographic hash of the default administrator password, used only when the container is first initialized; the default is to set no password; create the hash using docker run datalust/seq config hash and supply the password to STDIN |
What's next?
Once your apps are happily sending events to Seq, you can:
- Learn about the flexible Seq query syntax
- Create some signals to provide quick access to different filters
- Set up some retention policies to control disk usage
- Learn more about configuring Seq in Docker
Happy logging!
Updated almost 3 years ago