Habile iEYE on AWS Marketplace · HabileLabs
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.
| 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 |
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.
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:
<bucket>.s3.<region>.amazonaws.com, not from
the appliance. Their browsers need to reach that address; viewers on a closed network that
reaches only the VPC should use ebs. Live video is unaffected: it comes from the appliance
either way.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.
| 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) |
ConsoleUrl is the console; AdminPasswordSecret names a
Secrets Manager secret.The appliance serves HTTPS from the first minute, but with a certificate it issued itself, which browsers do not trust. Three ways out:
lets-encrypt, and make the stack internet-facing so port 80
is reachable. The appliance gets and renews the certificate itself.fullchain.pem and privkey.pem in
/var/lib/vms/data/certs on the instance, add the line
VMS_TLS=/certs/fullchain.pem /certs/privkey.pem to /opt/vms/compose/.env (for this
instance) and to /var/lib/vms/data/local.env (for the next one), and run
sudo systemctl restart vms. The certificate files and local.env are on the data volume,
so a version update keeps them.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.
| 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.
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
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.
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.
s3 it is small, and so are its
snapshots.s3, protect the bucket as you protect other footage: S3 Replication to another
Region or account if you need a second copy. Do not turn on versioning only for safety:
the appliance deletes expired recordings, and versions would keep every one of them billed.sudo xfs_growfs /var/lib/vms/data on the instance (a reboot does it too).
No downtime.DataVolume) in Use an existing data
volume and, with s3, the old bucket (RecordingBucket) in Use an existing bucket. The
new instance attaches them and carries on: cameras, users, recordings, settings. Sign in
with your existing password; the new stack's secret stays empty, since no first password is
created.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.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:
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./dev/sdf.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 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).
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.