How to self-host Log Owl

If you don't want to use the managed Log Owl service, you can host your own Log Owl instance in your own infrastructure. This article will help you set up own Log Owl instance.

Prerequisites for this guide

Step 0: Preparation

Before we can start, we need to create a Docker network, so that our Docker container, we are going to create in the next steps, are able to communicate with each other. You can create a Docker network with the command below.

docker network create logowl

Step 1: Setting up the database

Log Owl uses MongoDB as its persistence layer. If you already have a MongoDB running, you can skip this step. How you deploy MongoDB is up to you and depends on your use case. Covering all alternatives is out of the scope of this guide. Log Owl works with the latest version of MongoDB (4.2). If you are not familiar with MongoDB, we recommend using a managed MongoDB by provided by mLab or Atlas. Log Owl aggregates all data efficiently and therefore does not require a lot of space. How much it requires exactly, again, depends on your use case. For hobby projects without a budget, a sandbox environment might even be enough.

Run a local MongoDB container

In this guide, we are using a simple local MongoDB as Docker container. For large projects, we recommend more sophisticated configurations like replica sets. First, we need to create a directory, in which the data is stored. This ensured that data is persisted and won't be lost if the MongoDB container is removed. You can create such a directory anywhere, for example in ~/mongodb/data. Once you've created that directory, you can spin up a container with the command:

docker run \
-d \
-it \
-p 27017:27017 \
--name mongodb \
--network logowl \
-v ~/mongodb/data:/data/db \
mongo

This will run a MongoDB container with the name mongodb that is made available on port 27017 and runs in our logowl network from the previous step.

Creating admin user

Next, we need to create two users in our MongoDB for security reasons. One admin user that we can use to manage the MongoDB and one user that will be used by the Log Owl service. Open the MongoDB shell by typing mongo into the terminal, switch to the admin database with use admin and create a new user like shown below.

db.createUser({
user: "admin",
pwd: "password",
roles: [{ role: "userAdminAnyDatabase", db: "admin" }]
})

This will create an admin user that can manage all databases and users. Please make sure to replace the password with a strong one.

Add a MongoDB config

By default, authentication is disabled in MongoDB. To make sure only authenticated users access the database, we need to create a MongoDB config file in ~/mongodb/ with the name mongodb.conf and the following content:

security:
authorization: enabled

Now, we need to restart the Docker container. Run docker ps -a and find the container ID of the mongodb container and execute docker stop <container ID> && docker rm <container ID> to remove the container, we've created previously. We can now spin up a new container that uses the config file like so:

docker run \
-d \
-it \
-p 27017:27017 \
--name mongodb \
--network logowl \
-v ~/mongodb/mongodb.conf:/etc/mongodb.conf \
-v ~/mongodb/data:/data/db \
mongo -f /etc/mongodb.conf

Create a Log Owl database

As the last step, we need to create the Log Owl database and a user that has access to that database. Open the MongoDB shell again with mongo. You might have to wait a bit until the container is ready before you execute the mongo command. Now that authentication is required, we need to log in. To do so, switch to the admin database with use admin and log in with the credentials you've provided previously like so db.auth("admin", "password"). Next, we can create the Log Owl database with use logowl and a user with:

db.createUser({
user: "logowl-user",
pwd: "password",
roles: [{ role: "dbOwner", db: "logowl" }]
})

Again, please choose a strong password for the user. We've now set up a MongoDB with two users and a database. One is the admin of all databases, and the other is used to read and write to the logowl database by the Log Owl service, which we are going to set up in the next step.

caution

This is just a basic setup to get started. In production, you should implement additional security measurements such as IP whitelisting. A security checklist provided by MongoDB is linked at the bottom of this article. We recommend using replica sets for larger applications.

Step 2: Log Owl service

The Log Owl service is Log Owls backend. The easiest way to get started is using Log Owl with Docker. Simply run the command below to start a Log Owl service container on port 2800:

docker run \
--env PORT=2800 \
--env SECRET=secret \
--env MONGO_URI=mongodb://logowl-user:password@mongodb/logowl\?retryWrites=false \
--env MONGO_DB_NAME=logowl \
--env CLIENT_URL=http://localhost:8080 \
--env MONTHLY_REQUEST_LIMIT=100000 \
--env IS_SELFHOSTED=true \
-p 2800:2800 \
--network logowl \
-it \
jz222/logowl:2.0.0

Please make sure to use the latest Docker image and a strong SECRET. You can find the full configuration here.

note

If you are using a managed MongoDB instance like Atlas, you can omit the --network logowl flag.

Step 3: Log Owl client

Log Owl's client allows you to access and manage your data. The client is available as a static website that can be hosted as such. Firebase and Netlify provide easy solutions for hosting static websites. The static files can be found in the Log Owl client repository. The only thing you need to change before hosting it, is the backend URL. This URL must point to the service, which we've created in step 2. The URL can be set in the file config.js.

In our example, the Log Owl service is listening at http://localhost:2800, which is the default, so we don't have to change the config.js. To run the client locally, we need a local HTTP server. If you have npm installed, you can use this package to run the client locally by executing serve -s -p 8080 . inside the dist folder. This will make the client available at http://localhost:8080.

caution

It's important to host the client and the service on the same domain. In this example, the service, as well as the client, run on localhost. If you are running the service on localhost but the client on 127.0.0.1, it will not work. If you are using Log Owl in production, you could host the service at logowl-api.example.com and the client at logowl.example.com. In this example you need to update the environment variable CLIENT_URL in step 2 to https://logowl.example.com.

Step 4: Creating an organization

Now you can open http://localhost:8080/auth and create a new organization.

Further reading: