Rill on AWS User Guide

Overview

This image runs Rill, the open source operational business intelligence tool for building fast, interactive dashboards directly from your data. Rill pairs a code first data modelling workflow with an embedded DuckDB engine, so you define sources and metrics as simple configuration files and explore the results in a live dashboard with sub second queries, with no separate data warehouse or BI server to stand up.

Rill 0.87.4 is installed as the single rill binary at /usr/local/bin/rill and runs as a dedicated unprivileged rill system account under a systemd service that starts on boot and restarts on failure. The service runs rill start against a ready made sample project, so the web console shows a real dashboard the moment the instance is ready. The sample project, the embedded DuckDB storage and the Rill runtime home live on a dedicated, independently resizable EBS data volume mounted at /var/lib/rill, so your dashboards and data survive instance replacement.

Rill's local interface ships without authentication, so this image binds the Rill listener to loopback on 127.0.0.1:9009 and fronts it with an nginx reverse proxy on port 80 that enforces HTTP Basic authentication. A defence in depth firewall rule drops any off box traffic to the application port. The admin password is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a password. It is written to /root/rill-credentials.txt with mode 0600 so only the root user can read it. nginx also serves an unauthenticated /health endpoint used for health checks.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the web console
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Rill. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the web console. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation generates the admin password and writes the nginx credential store, and the web console is ready shortly after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Rill Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=rill}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Admin Password

The web console is protected by HTTP Basic authentication with the user admin. A unique password is generated on the first boot of each instance and written to a root only file. Read it with sudo:

sudo cat /root/rill-credentials.txt

The file records the sign in URL, the user admin and the generated RILL_ADMIN_PASSWORD. Store this password in your own secret manager; it is unique to this instance and no default login ships in the image.

Step 5: Sign in to the Rill Web Console

In a browser, go to http://<instance-public-ip>/. The browser prompts for HTTP Basic authentication: sign in with the user admin and the password from the previous step. Rill opens on the bundled cloudimg Sample Analytics project.

The left sidebar is the project workspace: sources and models shape your data, metrics defines the semantic layer of dimensions and measures, and dashboards holds the interactive Explore dashboards. Open the dashboards folder and select orders_explore to open the sample dashboard.

Step 6: Explore the Sample Dashboard

The sample project models a month of e commerce orders and exposes four measures, Total Revenue, Total Orders, Units Sold and Average Order Value, over three dimensions, Region, Category and Channel. Use the time range selector at the top to change the window, click a dimension value in a leaderboard to filter every measure by it, and use the comparison controls to compare periods. Switch to the Pivot view to build a cross tabulation of any measures against any dimensions and time grains, and export the result.

Step 7: Build a Dashboard From Your Own Data

Rill is a code first tool: a project is a directory of YAML and SQL files under /var/lib/rill. To point Rill at your own data, add a source, model it, describe a metrics view, and Rill generates the Explore dashboard.

1. In the workspace, use Add to create a new source, or drop a Parquet, CSV or NDJSON file into the project. You can also connect to ClickHouse, S3, GCS or Snowflake from the connectors panel.
2. Shape the source with a SQL model if needed.
3. Create a metrics view that names your timeseries column, your dimensions and your measures.
4. Rill generates an Explore dashboard over the metrics view, which you can open and refine.

The sample project under /var/lib/rill/sample is a complete, working example of this structure, a source (sources/orders.yaml), a metrics view (metrics/orders_metrics.yaml) and an Explore dashboard (dashboards/orders_explore.yaml), that you can copy and adapt.

Security Model

Rill's local runtime has no built in authentication, so this image layers two controls in front of it:

• HTTP Basic authentication at the edge. nginx on port 80 requires the admin user and the per instance password (stored in /etc/nginx/.htpasswd) before proxying any request to Rill. The unauthenticated /health endpoint is the only exception.
• Loopback binding and a firewall guard. The Rill runtime is reached only on 127.0.0.1:9009. A systemd managed nftables rule (rill-loopback-guard.service) drops any packet to port 9009 that does not arrive on the loopback interface, so the runtime is unreachable off box even if the port were bound to all interfaces, independent of your security group.

Keep your EC2 security group tight: expose port 22 only to your management network, and expose port 80 (and 443 once you add TLS) only to the clients that need the console.

Enable HTTPS

For production use, terminate TLS in front of nginx. The simplest path is to put the instance behind an Application Load Balancer with an AWS Certificate Manager certificate, forwarding to port 80. Alternatively, install a certificate directly in nginx and add a listen 443 ssl; server block. Open port 443 in the security group when you do.

The Data Volume

The sample project, the embedded DuckDB storage and the Rill runtime home live on a dedicated EBS volume mounted at /var/lib/rill, formatted ext4 and referenced in /etc/fstab by its filesystem UUID so it re attaches reliably. Because it is a separate volume from the operating system disk, you can grow it independently: expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs /dev/nvme1n1 (confirm the device with lsblk).

Managing the Service

Rill runs under systemd. Useful commands:

sudo systemctl status rill.service     # application status
sudo systemctl restart rill.service    # restart Rill
sudo journalctl -u rill.service -f     # follow the logs
sudo systemctl status nginx.service    # the reverse proxy

Support

Every cloudimg image is backed by 24/7 technical support by email and chat. We help with deployment, connecting your own data sources, authoring metrics views and dashboards, authentication, TLS and reverse proxy configuration, and storage sizing. Contact support@cloudimg.co.uk.

Rill is licensed under the Apache License 2.0. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.