Habile iEYE on AWS Marketplace · HabileLabs

Habile iEYE on AWS: deployment and operating guide

For the person deploying Habile iEYE from AWS Marketplace into their own AWS account. It is published as a page linked from the listing. The console's own Help centre covers using the system once it runs; this covers getting it there and keeping it healthy.

Before you start

You need Why
A subscription to Habile iEYE on AWS Marketplace AWS refuses to launch the AMI without one
A VPC and a subnet Public subnet for an internet-facing console; private subnet with a NAT gateway otherwise (the instance still needs outbound access for operating-system security updates and the EC2 API)
That subnet's Availability Zone The data volume is created there; the stack refuses a zone that is not the subnet's
A network path to your cameras The appliance reaches cameras over RTSP (usually 554) and ONVIF/HTTP (80/443). Cameras on a site network need a VPN, Direct Connect or a peered VPC
The address range your viewers come from The stack asks for it and has no default
An EC2 instance type, sized for your cameras See Choosing a size
Where recordings go: an S3 bucket (the default) or the EBS volume See Recording storage
With S3 and a private subnet: that subnet's route table ID The stack adds a free S3 endpoint to it, so uploads do not pass through the NAT gateway, which bills every GiB

Choosing a size

Recording is what the appliance spends its CPU and its disk on.

Size vCPU / memory Cameras at 2 MP, 15 fps
large 2 / 8 GiB about 24
xlarge 4 / 16 GiB about 64
2xlarge 8 / 32 GiB about 256
4xlarge 16 / 64 GiB about 750

These are design targets, so leave headroom and watch the CPU alarm for the first week. Version 1.0.0 runs no detection of its own, so these figures are for recording and viewing; a later version that detects in the appliance will need more CPU for the same cameras.

Each size comes in four families at the same software price: m7i, m8i (the newest) and m6i are Intel, m6a is AMD. Pick the cheapest instance in your Region: m6a usually is, at about half the price of m7i in Mumbai. large has no m6i.

750 cameras on one appliance is the ceiling this product is designed to, not a limit the software enforces. Above it, run more than one appliance and federate them, or move to the Kubernetes shape; write to us and we will size it with you.

How much video you keep is Σ (camera bitrate × retention). A 2 MP H.264 camera at 4 Mbit/s writes about 1.8 GiB an hour, about 43 GiB a day. Sixteen of them kept for 30 days need about 21 TiB. The two levers that change this by an order of magnitude are recording the substream instead of the main stream, and lowering camera bitrates — both are per-camera settings in the console. Size from your own cameras' real bitrates, not from this table.

Recording storage

Where recordings are kept decides where that video goes:

s3 (the default) ebs
Recordings, exports, timelapse frames An S3 bucket in your account The EBS volume
The EBS volume holds The database, exports being built, and segments waiting to upload All of it
Size the volume for The database and a bucket outage: 200 GiB suits most sites Your whole retention
Grows By itself When you extend the volume
Price a GiB-month (Mumbai) about a quarter of gp3 (cost-estimate.md) gp3, or st1 at a little over half of it
Recorded video reaches browsers Straight from the bucket, over HTTPS, with signed links that last minutes Through the appliance

With s3 the stack creates an encrypted bucket that blocks all public access and accepts only HTTPS, and gives the instance's role access to that bucket and no other. The appliance records each segment to the volume, uploads it when it is complete, checks the stored size, and only then deletes the local copy, so a segment is always playable from one place or the other. If the bucket cannot be reached, segments wait on the volume: a 2 MP camera at 4 Mbit/s fills about 1.8 GiB an hour, so a 200 GiB volume holds about three hours of 32 such cameras. The appliance deletes expired recordings from the bucket itself, at each camera's retention; the bucket has no versioning, so a deleted recording stops costing at once.

Two things to know before choosing it:

Use an existing bucket is for reusing one: the bucket an earlier stack kept (see Backup and recovery), or your own with your lifecycle or replication rules. It must be in the stack's Region, have no dots in its name, and be encrypted with SSE-S3 or the AWS managed key; the stack grants the instance access to it and changes nothing on the bucket itself.

With ebs everything is on the volume, as in the first versions: size it for your whole retention. gp3 suits most installations. st1 is about a third of the price and suits large archives that are written and read in long sequences, but it starts at 125 GiB and is slow at the small random reads that scrubbing a timeline does, so a timeline-heavy operations room should stay on gp3. With s3 the volume must be gp3: it holds the database.

Deploying

  1. From the listing, choose Continue to Subscribe, then Continue to Configuration, and pick the Appliance with CloudFormation delivery option and your Region.
  2. Launch opens CloudFormation with the template. Fill in:
Parameter Notes
VPC, Subnet, Availability Zone The subnet must belong to the VPC and the zone must be the subnet's: the console lists every VPC's subnets, and the stack refuses a mismatch before it creates anything
Reachable from vpc-only (no public address) or internet (an Elastic IP)
Who may open the console Required, no default. Your office or VPN range, or your VPC's own range
Who may reach SSH Leave empty. Use Session Manager instead; 0.0.0.0/0 is refused
Instance type From Choosing a size
Where recordings are kept, EBS data volume s3 (the default) or ebs, and the volume's size: Recording storage
Route table for an S3 endpoint Only with s3: give it with a private subnet
Use an existing data volume, Use an existing bucket Leave both empty for a new appliance. They bring back one an earlier stack kept (Backup and recovery), or move a stack from 4.1.0 or earlier (Updating)
Administrator e-mail The first sign-in name
Your host name, Certificate Leave as they are for a self-signed certificate; see Certificates
Alarm e-mail Gets the "ready" notice and every alarm
Permissions boundary for the instance role Leave empty, unless your account requires a boundary on every role. The policy you name must allow what the role grants (Session Manager, the stack's secret, topic, volume and bucket, CloudWatch metrics)
  1. Tick the IAM acknowledgement and create the stack. It reports CREATE_COMPLETE only when the console answers — about six minutes (measured: 6 min 12 s on an m7i.xlarge), most of it formatting the volume and running the database migrations.

First sign-in

  1. Open the stack's Outputs. ConsoleUrl is the console; AdminPasswordSecret names a Secrets Manager secret.
  2. Read that secret: it holds the administrator e-mail, the password generated on the instance, and the URL.
  3. Open the console. With a self-signed certificate the browser warns; accept it for now and read Certificates.
  4. Sign in and change the password immediately. The secret is then out of date; nothing rewrites it.
  5. Create an organisation, add its cameras, and give people accounts. The console's Help centre and its first-visit tour cover all of it.

Certificates

The appliance serves HTTPS from the first minute, but with a certificate it issued itself, which browsers do not trust. Three ways out:

Live video and the network

Live video does not go through the console's HTTPS port. The browser connects to the media server directly over WebRTC on port 8189, UDP with a TCP fallback, which is why the stack opens it to the same range as the console. If viewers are behind strict NAT, set a STUN/TURN server (VMS_ICE_SERVER_URL and its credentials) in /opt/vms/compose/.env and restart; put the same lines in /var/lib/vms/data/local.env so the next instance keeps them.

If you stop and start the instance rather than rebooting it, and you did not choose an internet-facing endpoint, its address changes and the addresses announced for WebRTC go stale. Fix it by editing VMS_WEBRTC_HOSTS and VMS_PUBLIC_URL in /opt/vms/compose/.env and restarting the appliance. Not in local.env: those addresses belong to this instance, and the next one works out its own.

Where your data is

What Where
Recordings, exports, timelapse frames With s3: the bucket in the stack output RecordingBucket, and segments still uploading in /var/lib/vms/data/recordings. With ebs: /var/lib/vms/data on the encrypted EBS volume
The database (cameras, users, events, audit) /var/lib/vms/data/pgdata on the encrypted EBS volume, either way
Camera credentials In the database, encrypted
The appliance's own secrets (database passwords, the key camera credentials are encrypted with) /var/lib/vms/data/secrets on the EBS volume, mode 0700, linked from /opt/vms/compose/secrets. Generated on the first instance, and kept with the database they open
Certificates, and your own settings /var/lib/vms/data/caddy (the appliance's root and any Let's Encrypt certificate), /var/lib/vms/data/certs and /var/lib/vms/data/local.env, on the EBS volume
Logs journalctl and Docker's logs, capped at 50 MB × 5 per container. No credentials and no stream URLs

Nothing is sent to HabileLabs. The appliance's only outbound connections are to your cameras, your own S3 bucket (with s3), the notification services you configure, and Ubuntu and Docker package mirrors for security updates.

The resources the stack creates carry the tag aws-apn-id-941275879372 with the value pc:6que8h9hmw1pwkjl7io2vncgh. It tells AWS that they run HabileLabs' product, for AWS's partner programme (AWS Partner Revenue Measurement). It holds nothing from the appliance, costs nothing, and the appliance does not read it. A data volume you name in Use an existing data volume gets it from the appliance when it first starts on it; a bucket you name in Use an existing bucket is left as it is. You can remove it; an update to a new version puts it back.

Getting a shell

Use Session Manager — the instance role the stack creates allows it, and no port has to be open:

aws ssm start-session --target <InstanceId>

Or the SessionManagerUrl in the stack outputs. SSH is closed unless you gave the stack an address range and a key pair, and password logins are refused either way.

Useful once you are on it:

systemctl status vms                 # the appliance
journalctl -u vms-firstboot          # what the first boot did
cd /opt/vms/compose && docker compose -f docker-compose.yml -f docker-compose.aws.yml ps
sudo vms-support                     # a diagnostic bundle for support@habilelabs.io

Monitoring

The stack creates four alarms on the topic in AlarmTopicArn:

Alarm What it means
System status check The AWS hardware under the instance failed. EC2 recovers the instance in place, which keeps the volume, the address and the recordings
Instance status check The appliance is not answering. Nothing is being recorded while this lasts
Data volume over 85 % With ebs: lower retention on some cameras, record their substream, or extend the volume. With s3: segments are not leaving the volume — check that the instance still reaches S3 (the NAT gateway or the S3 endpoint) and the bucket still exists
CPU over 90 % for half an hour Live video and detection suffer first. Move to a larger instance type, or record fewer streams

Subscribe your on-call to that topic. The console also keeps its own camera health: online and recording status, outages per camera, and a daily digest by e-mail.

Backup and recovery

The data volume and, with s3, the bucket are the state. Nothing else on the instance is irreplaceable: the root volume is rebuilt from the AMI, and the configuration is regenerated. The volume holds the database, the keys that open it, and the certificates; the database is the index of the footage: a bucket without it holds video nobody can find in the console. The stack output DataVolume names the volume.

Updating

  1. Subscribe to the new version in AWS Marketplace.
  2. Update the stack with the new version's template (Replace current template), keeping your parameter values.
  3. CloudFormation starts a new instance from the new version. At its first boot it stops the old instance — which shuts the appliance down cleanly — moves the data volume over and starts the appliance on it: the database, cameras, users, settings, keys, certificates and (with ebs) the recordings, as they were. Then CloudFormation deletes the old instance. Recording stops from the moment the old instance stops until the new one is up, a few minutes, so do it in a quiet window.
  4. If the new instance cannot bring the appliance up, it gives the volume back to the old instance, starts that again, and the update rolls back to it. If the console is still down after a rollback, start the old instance in the EC2 console: it re-attaches its data volume by itself.

With Reachable from: internet the Elastic IP moves to the new instance, so nothing changes for viewers. With vpc-only the new instance has a new private address: the outputs ConsoleUrl and ConsoleAddress show it, so point your host name at it. Keep the subnet: a volume cannot leave its Availability Zone, and an update that would start the appliance on a new, empty volume stops before it changes anything.

A stack created with version 4.1.0 or earlier keeps its data volume as part of its instance and the appliance's keys on that instance's own disk, so updating it as above would start on an empty volume — the update stops and says so instead. Move it once:

  1. Open a shell on the instance (Session Manager) and run sudo sh -c 'cp -a /opt/vms/compose/secrets /var/lib/vms/data/ && touch /var/lib/vms/data/.admin-created'. That copies the keys onto the data volume and records that its administrator exists.
  2. In the EC2 console, open the instance's Storage tab and note the volume at /dev/sdf.
  3. Update the stack with the new template and set Availability Zone to the subnet's zone, Use an existing data volume to that volume, and Where recordings are kept to ebs (the new default is s3; ebs keeps recording where you always have. Moving existing footage into a bucket is a separate step, which support will walk you through).

From then on, updates are the four steps above.

Operating-system security updates apply themselves on the instance and never reboot it; a reboot stays your decision.

Deleting

Deleting the stack keeps the data volume and the recording bucket — your footage is the one thing that cannot be recreated, and a new stack can pick both up again (Backup and recovery). The Elastic IP, the security group, the role, the S3 endpoint, the secret, the topic and the alarms all go. Delete the volume yourself in the EC2 console once you no longer need what is on it, or snapshot it first; empty and delete the bucket in the S3 console (or aws s3 rb s3://<bucket> --force). A volume or bucket you named in Use an existing ... was never the stack's, and stays as it was, but for the partner tag on a volume (Where your data is).

Getting help

Start with the console's own help centre (the ? button, or /help): user, administrator and platform guides, and a first-visit tour you can take again from the account menu. This guide covers the deployment; the help centre covers using the system.

Then e-mail support@habilelabs.io with your AWS account ID, the stack name, and the bundle from sudo vms-support (no video, no credentials, no database contents — it is safe to send). Office hours are 10:00-19:00 IST, Monday to Friday.

What you can expect depends on the instance type you subscribed to:

Instance type Response
2xlarge, 4xlarge, of any family We aim to answer within one business day, and within four office hours when the system is down or recording has stopped
large, xlarge, of any family Self-service with best-effort e-mail: we read every message and answer as soon as we can, but do not commit to a response time

If you want a response target on a small installation, ask us for a private offer.