Atlas

Thingspect IoT platform

Getting Started

Install any compliant package of Docker, Docker Compose, and Go. Consider using Colima:

brew install colima docker docker-compose docker-buildx
colima start --cpu 3 --memory 3 --disk 16 --mount-type virtiofs --mount ~/code/go:w --vz-rosetta

Run the build and tests:

docker compose -f build/docker-compose.yml up -d
make test
RACE=y make test
docker compose -f build/docker-compose.yml down

Running an API Locally

First complete the above steps, leaving dependency containers running. Then:

atlas-create org testorg testadmin@thingspect.com testpass
API_PWT_KEY=$(dd if=/dev/random bs=1 count=32|base64) API_API_HOST=127.0.0.1 atlas-api

curl -v -X POST -d '{"email":"testadmin@thingspect.com", "orgName":"testorg", "password":"testpass"}' http://localhost:8000/v1/sessions/login

OpenAPI live docs are available at http://localhost:8000/.

Tutorial

Getting started with the Atlas API:

• Log in with /v1/sessions/login using your provided credentials. Click Authorize below and enter the returned token.
• (Optional) Create an BUILDER role API key with /v1/sessions/keys. Re-authorize using the returned token.

Publish and verify data points:

• Create a device with /v1/devices. Include a notable tag for future use.
• Publish data with /v1/datapoints. The attr and val fields can be arbitrarily chosen.
• Inspect the received data with /v1/datapoints/latest using the device's uniqID.

Publish data points and receive alerts:

• Update your user with /v1/users/{user.id} to include a notable tag.
• Create a rule with /v1/rules. The deviceTag field should match a tag of the device. The expr field can be simply true.
• Create an alarm with /v1/rules/{alarm.ruleID}/alarms. The type field should match data that is available in the user's fields, such as EMAIL. The userTags field should include a tag of the user.
• Publish data for the device, as done in the previous section. The attr field should match the attr of the rule.
• Verify the alert is received by the user on the configured type method.
• Inspect the created event with /v1/events using the device's uniqID.
• Inspect the created alert with /v1/alerts using the device's uniqID.

Deploying

Docker Compose files for the Atlas platform and its dependencies are available in build/deploy/. These can be used for a single-system deploy, or as templates for orchestration tooling such as Nomad or Kubernetes. Keys should be provided where applicable.

Use of Build Tags In Tests

All non-generated test files should have build tags, including main_test.go. Due to limitations of developer tools and extensions, negated tags are used.

For example, to tag a file as a unit test:

// +build !integration

To tag a file as an integration test:

// +build !unit

To find test files that are missing build tags, the following command can be run:

find . -name '*_test.go' -type f|grep -v /mock_|xargs grep -L '//go:build'