### Complete Rotation Example

Source: https://github.com/absmach/magistrala/blob/main/auth/tokenizer/asymmetric/README.md

A step-by-step example demonstrating a complete key rotation process, including initial setup, new key generation, configuration updates, and cleanup.

```bash
# Day 0: Normal operation
export MG_AUTH_KEYS_ACTIVE_KEY_PATH="./keys/key-2024.pem"
export MG_AUTH_KEYS_RETIRING_KEY_PATH=""

# Day 1: Start rotation - generate new key
openssl genpkey -algorithm Ed25519 -out ./keys/key-2025.pem
chmod 600 ./keys/key-2025.pem

# Day 1: Update config and restart
export MG_AUTH_KEYS_ACTIVE_KEY_PATH="./keys/key-2025.pem"
export MG_AUTH_KEYS_RETIRING_KEY_PATH="./keys/key-2024.pem"
docker-compose restart auth

# Day 8: Grace period expired - remove old key
export MG_AUTH_KEYS_RETIRING_KEY_PATH=""
docker-compose restart auth
rm ./keys/key-2024.pem
```

--------------------------------

### Compile and Install Timescale Writer

Source: https://github.com/absmach/magistrala/blob/main/consumers/writers/timescale/README.md

Steps to download, compile, and install the Timescale writer binary.

```bash
git clone https://github.com/absmach/magistrala

cd magistrala

# compile the timescale writer
make timescale-writer

# copy binary to bin
make install
```

--------------------------------

### Compile and Install Postgres Writer

Source: https://github.com/absmach/magistrala/blob/main/consumers/writers/postgres/README.md

Steps to download, compile, and install the postgres writer service binary.

```bash
# download the latest version of the service
git clone https://github.com/absmach/magistrala

cd magistrala

# compile the postgres writer
make postgres-writer

# copy binary to bin
make install

```

--------------------------------

### Start Addon Services

Source: https://github.com/absmach/magistrala/blob/main/docker/README.md

Starts additional Magistrala addon services using a specific compose file.

```bash
docker compose -f docker/addons/<path>/docker-compose.yaml --env-file docker/.env up
```

--------------------------------

### Start Source Databases

Source: https://github.com/absmach/magistrala/blob/main/tools/atom-migration/README.md

Starts the required source database containers using Docker Compose without starting dependent application services.

```bash
docker compose -f docker/docker-compose.yaml up -d --no-deps \
  auth-db users-db workspaces-db devices-db channels-db groups-db \
  re-db reports-db
```

--------------------------------

### Install MQTT Bench Tool

Source: https://github.com/absmach/magistrala/blob/main/tools/mqtt-bench/README.md

Build the MQTT benchmarking tool using make. Navigate to the tool's directory first.

```bash
cd tools/mqtt-bench
make
```

--------------------------------

### Wildcard Subtopic Example

Source: https://github.com/absmach/magistrala/blob/main/pkg/transformers/json/README.md

An example URL using a wildcard to subscribe to any message format.

```text
http://localhost:8185/m/<workspace_id>/c/<channelID>/home/temperature/#
```

--------------------------------

### Create a Device Using PAT

Source: https://github.com/absmach/magistrala/blob/main/auth/README.md

Example of using a PAT to authenticate a request to create a device within a specific workspace.

```bash
curl --location 'http://localhost:9006/c16c980a-9d4c-4793-8fb2-c81304cf1d9f/devices' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer pat_etKoiXKTR6a0zdgsBHC00qJQAiaV3EKFh+Lmk+SgqXY=_u7@5fyjgti9V@#Bw^bS*SPmX3OnH=HTvKwmIbxIuyBjoI|6FASo9egjKD^u-M$b|2Dpt3CXZtv&4k+hmYYjk&C$57AV59P%-iDV0' \
--data '{
  "name": "test device",
  "tags": [
    "tag1",
    "tag2"
  ],
  "metadata":{"units":"km"},
  "status": "enabled"
}'
```

--------------------------------

### Run Timescale Writer with Environment Variables

Source: https://github.com/absmach/magistrala/blob/main/consumers/writers/timescale/README.md

Example of how to set environment variables and run the Timescale writer service.

```bash
# Set the environment variables and run the service
MG_TIMESCALE_WRITER_LOG_LEVEL=[Service log level] \
MG_TIMESCALE_WRITER_CONFIG_PATH=[Configuration file path with Message broker subjects list] \
MG_TIMESCALE_WRITER_HTTP_HOST=[Service HTTP host] \
MG_TIMESCALE_WRITER_HTTP_PORT=[Service HTTP port] \
MG_TIMESCALE_WRITER_HTTP_SERVER_CERT=[Service HTTP server cert] \
MG_TIMESCALE_WRITER_HTTP_SERVER_KEY=[Service HTTP server key] \
MG_TIMESCALE_HOST=[Timescale host] \
MG_TIMESCALE_PORT=[Timescale port] \
MG_TIMESCALE_USER=[Timescale user] \
MG_TIMESCALE_PASS=[Timescale password] \
MG_TIMESCALE_NAME=[Timescale database name] \
MG_TIMESCALE_SSL_MODE=[Timescale SSL mode] \
MG_TIMESCALE_SSL_CERT=[Timescale SSL cert] \
MG_TIMESCALE_SSL_KEY=[Timescale SSL key] \
MG_TIMESCALE_SSL_ROOT_CERT=[Timescale SSL Root cert] \
MG_MESSAGE_BROKER_URL=[Message broker instance URL] \
MG_JAEGER_URL=[Jaeger server URL] \
MG_SEND_TELEMETRY=[Send telemetry to magistrala call home server] \
MG_TIMESCALE_WRITER_INSTANCE_ID=[Timescale writer instance ID] \
$GOBIN/magistrala-timescale-writer
```

--------------------------------

### Subtopic Format Example

Source: https://github.com/absmach/magistrala/blob/main/pkg/transformers/json/README.md

An example URL showing how the message format is included as the last part of the subtopic.

```text
http://localhost:8008/m/<workspace_id>/c/<channelID>/home/temperature/myFormat
```

--------------------------------

### Example config.toml Structure

Source: https://github.com/absmach/magistrala/blob/main/tools/mqtt-bench/README.md

A sample TOML configuration file for the MQTT benchmarking tool. It defines settings for the MQTT broker, messages, TLS, test parameters, logging, and Magistrala connections.

```toml
[mqtt]
[mqtt.broker]
url = "tcp://localhost:1883"

[mqtt.message]
size = 100
format = "text"
qos = 2
retain = true

[mqtt.tls]
mtls = false
skiptlsver = true
ca = "ca.crt"

[test]
pubs = 3
count = 100

[log]
quiet = false

[magistrala]
connections_file = "smqconn.toml"

```

--------------------------------

### Launch Updated Deployment

Source: https://github.com/absmach/magistrala/blob/main/tools/atom-migration/README.md

Execute this command after the migration process completes to start the new deployment with the migrated data.

```bash
# stop the old stack, then:
make run_latest
```

--------------------------------

### PAT Creation Response

Source: https://github.com/absmach/magistrala/blob/main/auth/README.md

Example JSON response returned after successfully creating a new PAT.

```json
{
  "id": "a2500226-95dc-4285-87e2-e693e4a0a976",
  "user_id": "user123",
  "name": "pat 1",
  "description": "for creating any device or channel",
  "secret": "pat_dXNlcjEyM19hMjUwMDIyNi05NWRjLTQyODUtODdlMi1lNjkzZTRhMGE5NzY=_randomstring...",
  "issued_at": "2025-02-27T11:20:59Z",
  "expires_at": "2025-02-28T11:20:59Z"
}
```

--------------------------------

### Deploy writers with Docker Compose

Source: https://github.com/absmach/magistrala/blob/main/consumers/writers/README.md

Commands to start the Postgres writer add-on or the Timescale writer using Docker Compose.

```bash
docker compose -f docker/docker-compose.yaml -f docker/addons/postgres-writer/docker-compose.yaml up
```

```bash
docker compose -f docker/docker-compose.yaml up
```

--------------------------------

### Run Magistrala locally

Source: https://github.com/absmach/magistrala/blob/main/README.md

Commands to clone the repository and start the full stack using Docker Compose.

```bash
git clone https://github.com/absmach/magistrala.git
cd magistrala
make run_latest
```

--------------------------------

### Define a Device with Gateway Reachability

Source: https://github.com/absmach/magistrala/blob/main/edge/architecture.md

Example of a device object definition showing its serial, type, and the gateways through which it is reachable.

```text
Device  meter-7 { serial: "WM-2024-ABC.123", type: watermeter-v2,
                  gateways: ["gw-a", "gw-b"] }
```

--------------------------------

### Define Gateway Address Configuration

Source: https://github.com/absmach/magistrala/blob/main/edge/architecture.md

Example of the JSON structure used to define gateway addresses, where the address is treated as an opaque blob.

```jsonc
"gateways": [
  { "id": "gw-a", "address": { "modbus_unit": 7 } },
  { "id": "gw-b" }
]
```

--------------------------------

### Define Device and Gateway Entities

Source: https://github.com/absmach/magistrala/blob/main/edge/architecture.md

Example JSON structure for a device linked to multiple gateways and the corresponding gateway entity definition.

```jsonc
// Atom entity — a wM-Bus meter reachable through two gateways
{
  "id":          "018f...",              // Atom UUID
  "kind":        "device",
  "external_id": "WM-2024-ABC.123",      // the serial; what appears in topics
  "attributes": {
    "is_gateway": false,
    "gateways":   ["018a-gw-a", "018b-gw-b"]     // phase 1: IDs only
  }
}

// The gateway itself — same kind, one flag different
{
  "id":          "018a-gw-a",
  "kind":        "device",
  "external_id": "GW-SITE-5",
  "attributes":  { "is_gateway": true }
}
```

--------------------------------

### Bootstrap a device with the SDK

Source: https://github.com/absmach/magistrala/blob/main/pkg/sdk/README.md

Configures a new device using the BootstrapConfig struct and registers it via AddBootstrap.

```go
ctx := context.Background()

cfg := sdk.BootstrapConfig{
    ExternalID:  "external-id",
    ExternalKey: "external-key",
    Channels:    []string{channelID},
    Name:        "My Device",
}
id, err := smqsdk.AddBootstrap(ctx, cfg, workspaceID, token)
```

--------------------------------

### Initializing and Using the Magistrala SDK

Source: https://github.com/absmach/magistrala/blob/main/pkg/sdk/README.md

Configure the SDK with service URLs and use the instance to interact with Magistrala services like sending messages.

```go
import (
    "context"
    "fmt"
    "github.com/absmach/magistrala/pkg/sdk"
)

func main() {
    conf := sdk.Config{
        CertsURL:       "http://localhost:9019",
        HTTPAdapterURL: "http://localhost:8008",
        BootstrapURL:   "http://localhost:9013",
        ReaderURL:      "http://localhost:9011",
        AlarmsURL:      "http://localhost:9021",
        ReportsURL:     "http://localhost:9022",
        RulesEngineURL: "http://localhost:9023",
        HostURL:        "http://localhost",
    }

    // Create SDK instance
    smqsdk := sdk.NewSDK(conf)

    ctx := context.Background()

    // Send a message to a channel (token/secret obtained from Atom)
    if err := smqsdk.SendMessage(ctx, workspaceID, "channelID", `{"value":42}`, secret); err != nil {
        fmt.Printf("Error sending message: %v\n", err)
        return
    }
}
```

--------------------------------

### Run MQTT Bench Tool with Config File

Source: https://github.com/absmach/magistrala/blob/main/tools/mqtt-bench/README.md

Execute the MQTT benchmarking tool using a TOML configuration file for all settings. This simplifies command-line arguments.

```bash
go run tools/mqtt-bench/cmd/main.go --config tools/mqtt-bench/config.toml
```

--------------------------------

### Example Health Check Response

Source: https://github.com/absmach/magistrala/blob/main/consumers/README.md

This is an example response from the health check endpoint, indicating the service status, version, and build time.

```json
{
  "status": "pass",
  "version": "0.15.1",
  "description": "notifiers service",
  "build_time": "YYYY‑MM‑DDTHH:MM:SSZ"
}

```

--------------------------------

### GET /pats

Source: https://github.com/absmach/magistrala/blob/main/auth/README.md

Lists all PATs for the authenticated user.

```APIDOC
## GET /pats

### Description
Retrieves a list of all Personal Access Tokens associated with the user.

### Method
GET

### Endpoint
/pats
```

--------------------------------

### Set Environment Variables and Run Postgres Writer

Source: https://github.com/absmach/magistrala/blob/main/consumers/writers/postgres/README.md

Configure the service by setting environment variables for logging, configuration paths, network settings, database connection details, message broker URL, tracing, telemetry, and instance ID. Then, execute the service binary.

```bash
MG_POSTGRES_WRITER_LOG_LEVEL=[Service log level] \
MG_POSTGRES_WRITER_CONFIG_PATH=[Config file path with Message broker subjects list, payload type and content-type] \
MG_POSTGRES_WRITER_HTTP_HOST=[Service HTTP host] \
MG_POSTGRES_WRITER_HTTP_PORT=[Service HTTP port] \
MG_POSTGRES_WRITER_HTTP_SERVER_CERT=[Service HTTP server cert] \
MG_POSTGRES_WRITER_HTTP_SERVER_KEY=[Service HTTP server key] \
MG_POSTGRES_HOST=[Postgres host] \
MG_POSTGRES_PORT=[Postgres port] \
MG_POSTGRES_USER=[Postgres user] \
MG_POSTGRES_PASS=[Postgres password] \
MG_POSTGRES_NAME=[Postgres database name] \
MG_POSTGRES_SSL_MODE=[Postgres SSL mode] \
MG_POSTGRES_SSL_CERT=[Postgres SSL cert] \
MG_POSTGRES_SSL_KEY=[Postgres SSL key] \
MG_POSTGRES_SSL_ROOT_CERT=[Postgres SSL Root cert] \
MG_MESSAGE_BROKER_URL=[Message broker instance URL] \
MG_JAEGER_URL=[Jaeger server URL] \
MG_SEND_TELEMETRY=[Send telemetry to magistrala call home server] \
MG_POSTGRES_WRITER_INSTANCE_ID=[Service instance ID] \

$GOBIN/magistrala-postgres-writer
```

--------------------------------

### Deploy and run Timescale reader

Source: https://github.com/absmach/magistrala/blob/main/readers/timescale/README.md

Commands to clone the repository, compile the binary, and execute the service with required environment variables.

```bash
# download the latest version of the service
git clone https://github.com/absmach/magistrala

cd magistrala

# compile the timescale writer
make timescale-writer

# copy binary to bin
make install

# Set the environment variables and run the service
MG_TIMESCALE_READER_LOG_LEVEL=[Service log level] \
MG_TIMESCALE_READER_HTTP_HOST=[Service HTTP host] \
MG_TIMESCALE_READER_HTTP_PORT=[Service HTTP port] \
MG_TIMESCALE_READER_HTTP_SERVER_CERT=[Service HTTP server cert] \
MG_TIMESCALE_READER_HTTP_SERVER_KEY=[Service HTTP server key] \
MG_TIMESCALE_HOST=[Timescale host] \
MG_TIMESCALE_PORT=[Timescale port] \
MG_TIMESCALE_USER=[Timescale user] \
MG_TIMESCALE_PASS=[Timescale password] \
MG_TIMESCALE_NAME=[Timescale database name] \
MG_TIMESCALE_SSL_MODE=[Timescale SSL mode] \
MG_TIMESCALE_SSL_CERT=[Timescale SSL cert] \
MG_TIMESCALE_SSL_KEY=[Timescale SSL key] \
MG_TIMESCALE_SSL_ROOT_CERT=[Timescale SSL Root cert] \
MG_DEVICES_GRPC_URL=[Devices service Auth GRPC URL] \
MG_DEVICES_GRPC_TIMEOUT=[Clients  service Auth gRPC request timeout in seconds] \
MG_DEVICES_GRPC_CLIENT_TLS=[Clients  service Auth gRPC TLS enabled flag] \
MG_DEVICES_GRPC_CA_CERTS=[Clients  service Auth gRPC CA certificates] \
MG_AUTH_GRPC_URL=[Auth service Auth gRPC URL] \
MG_AUTH_GRPC_TIMEOUT=[Auth service Auth gRPC request timeout in seconds] \
MG_AUTH_GRPC_CLIENT_TLS=[Auth service Auth gRPC TLS enabled flag] \
MG_AUTH_GRPC_CA_CERT=[Auth service Auth gRPC CA certificates] \
MG_JAEGER_URL=[Jaeger server URL] \
MG_SEND_TELEMETRY=[Send telemetry to magistrala call home server] \
MG_TIMESCALE_READER_INSTANCE_ID=[Timescale reader instance ID] \
$GOBIN/magistrala-timescale-reader
```

--------------------------------

### GET /subscriptions

Source: https://github.com/absmach/magistrala/blob/main/consumers/notifiers/README.md

Lists subscriptions with optional filtering.

```APIDOC
## GET /subscriptions

### Description
List subscriptions with filters.

### Method
GET

### Endpoint
/subscriptions

### Query Parameters
- **topic** (string) - Optional - Filter by topic.
- **contact** (string) - Optional - Filter by contact.
- **limit** (integer) - Optional - Limit the number of results.
- **offset** (integer) - Optional - Offset for pagination.
```

--------------------------------

### GET /health

Source: https://github.com/absmach/magistrala/blob/main/consumers/notifiers/README.md

Checks the health status of the Notifiers service.

```APIDOC
## GET /health

### Description
Service health check.

### Method
GET

### Endpoint
/health
```

--------------------------------

### Example JSON Input

Source: https://github.com/absmach/magistrala/blob/main/pkg/transformers/json/README.md

A nested JSON object structure before transformation.

```json
{
    "name": "name",
    "id":8659456789564231564,
    "in": 3.145,
    "alarm": true,
    "ts": 1571259850000,
    "d": {
        "tmp": 2.564,
        "hmd": 87,
        "loc": {
            "x": 1,
            "y": 2
        }
    }
}
```

--------------------------------

### Build the Atom Migration Tool

Source: https://github.com/absmach/magistrala/blob/main/tools/atom-migration/README.md

Commands to build the tool as a binary or as a Docker image.

```bash
go build ./tools/atom-migration/
```

```bash
docker build -f tools/atom-migration/Dockerfile -t magistrala/atom-migration:dev .
```

--------------------------------

### GET /subscriptions/{id}

Source: https://github.com/absmach/magistrala/blob/main/consumers/notifiers/README.md

Retrieves details of a specific subscription by its ID.

```APIDOC
## GET /subscriptions/{id}

### Description
Retrieve a subscription.

### Method
GET

### Endpoint
/subscriptions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the subscription.
```

--------------------------------

### Device attribute representation

Source: https://github.com/absmach/magistrala/blob/main/edge/prd/ATOM-01-entity-attribute-filter.md

Example of how device-to-gateway relations are stored as attributes on a device.

```text
Device meter-7 { gateways: ["gw-a", "gw-b"] }        // phase 1: IDs
```

--------------------------------

### Manage Bootstrap Configurations

Source: https://github.com/absmach/magistrala/blob/main/pkg/sdk/README.md

Methods for managing bootstrap configurations, profiles, and resource bindings.

```go
// Manage bootstrap configs
AddBootstrap(ctx context.Context, cfg BootstrapConfig, workspaceID, token string) (string, errors.SDKError)
ViewBootstrap(ctx context.Context, id, workspaceID, token string) (BootstrapConfig, errors.SDKError)
UpdateBootstrap(ctx context.Context, cfg BootstrapConfig, workspaceID, token string) errors.SDKError
UpdateBootstrapCerts(ctx context.Context, id string, clientCert, clientKey, ca string, workspaceID, token string) (BootstrapConfig, errors.SDKError)
RemoveBootstrap(ctx context.Context, id, workspaceID, token string) errors.SDKError
Bootstraps(ctx context.Context, pm PageMetadata, workspaceID, token string) (BootstrapPage, errors.SDKError)

// Device-facing bootstrap retrieval
Bootstrap(ctx context.Context, externalID, externalKey string) (BootstrapConfig, errors.SDKError)
BootstrapSecure(ctx context.Context, externalID, externalKey, cryptoKey string) (BootstrapConfig, errors.SDKError)
Whitelist(ctx context.Context, id string, status BootstrapStatus, workspaceID, token string) errors.SDKError

// Bootstrap profiles
CreateBootstrapProfile(ctx context.Context, profile BootstrapProfile, workspaceID, token string) (BootstrapProfile, errors.SDKError)
ViewBootstrapProfile(ctx context.Context, id, workspaceID, token string) (BootstrapProfile, errors.SDKError)
UpdateBootstrapProfile(ctx context.Context, profile BootstrapProfile, workspaceID, token string) errors.SDKError
RemoveBootstrapProfile(ctx context.Context, id, workspaceID, token string) errors.SDKError
BootstrapProfiles(ctx context.Context, pm PageMetadata, workspaceID, token string) (BootstrapProfilesPage, errors.SDKError)
AssignBootstrapProfile(ctx context.Context, configID, profileID, workspaceID, token string) errors.SDKError

// Bootstrap enrollments
BindBootstrapResources(ctx context.Context, configID string, bindings []BootstrapBindingRequest, workspaceID, token string) errors.SDKError
BootstrapBindings(ctx context.Context, configID, workspaceID, token string) ([]BootstrapBindingSnapshot, errors.SDKError)
RefreshBootstrapBindings(ctx context.Context, configID, workspaceID, token string) errors.SDKError
```

--------------------------------

### GET /pats/{id}/scopes

Source: https://github.com/absmach/magistrala/blob/main/auth/README.md

Lists all scopes associated with a specific PAT.

```APIDOC
## GET /pats/{id}/scopes

### Description
Retrieves the list of scopes defined for a specific PAT.

### Method
GET

### Endpoint
/pats/{id}/scopes

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the PAT
```

--------------------------------

### Run MQTT Bench Tool (No mTLS)

Source: https://github.com/absmach/magistrala/blob/main/tools/mqtt-bench/README.md

Execute the MQTT benchmarking tool with standard TCP connection to the broker. Configure message count, size, QoS, publisher count, and the Magistrala connection file.

```bash
go run tools/mqtt-bench/cmd/main.go --broker tcp://localhost:1883 --count 100 --size 100 --qos 0 --format text --pubs 10 --magistrala tools/mqtt-bench/mgconn.toml
```

--------------------------------

### Create Workspace

Source: https://github.com/absmach/magistrala/blob/main/apidocs/graphql/README.md

Create a new tenant workspace.

```graphql
mutation {
  createTenant(input: {
    name: "factory-a"
    alias: "factory-a"
  }) {
    id
    name
    alias
    status
  }
}
```

--------------------------------

### Deploy and run Postgres reader service

Source: https://github.com/absmach/magistrala/blob/main/readers/postgres/README.md

Use this script to clone the repository, compile the binary, and execute the service with required environment variables.

```bash
# download the latest version of the service
git clone https://github.com/absmach/magistrala

cd magistrala

# compile the postgres writer
make postgres-writer

# copy binary to bin
make install

# Set the environment variables and run the service
MG_POSTGRES_READER_LOG_LEVEL=[Service log level] \
MG_POSTGRES_READER_HTTP_HOST=[Service HTTP host] \
MG_POSTGRES_READER_HTTP_PORT=[Service HTTP port] \
MG_POSTGRES_READER_HTTP_SERVER_CERT=[Service HTTPS server certificate path] \
MG_POSTGRES_READER_HTTP_SERVER_KEY=[Service HTTPS server key path] \
MG_POSTGRES_HOST=[Postgres host] \
MG_POSTGRES_PORT=[Postgres port] \
MG_POSTGRES_USER=[Postgres user] \
MG_POSTGRES_PASS=[Postgres password] \
MG_POSTGRES_NAME=[Postgres database name] \
MG_POSTGRES_SSL_MODE=[Postgres SSL mode] \
MG_POSTGRES_SSL_CERT=[Postgres SSL cert] \
MG_POSTGRES_SSL_KEY=[Postgres SSL key] \
MG_POSTGRES_SSL_ROOT_CERT=[Postgres SSL Root cert] \
MG_DEVICES_GRPC_URL=[Devices service Auth GRPC URL] \
MG_DEVICES_GRPC_TIMEOUT=[Devices service Auth gRPC request timeout in seconds] \
MG_DEVICES_GRPC_CLIENT_TLS=[Devices service Auth gRPC TLS mode flag] \
MG_DEVICES_GRPC_CA_CERTS=[Devices service Auth gRPC CA certificates] \
MG_AUTH_GRPC_URL=[Auth service gRPC URL] \
MG_AUTH_GRPC_TIMEOUT=[Auth service gRPC request timeout in seconds] \
MG_AUTH_GRPC_CLIENT_TLS=[Auth service gRPC TLS mode flag] \
MG_AUTH_GRPC_CA_CERTS=[Auth service gRPC CA certificates] \
MG_JAEGER_URL=[Jaeger server URL] \
MG_SEND_TELEMETRY=[Send telemetry to magistrala call home server] \
MG_POSTGRES_READER_INSTANCE_ID=[Postgres reader instance ID] \
$GOBIN/magistrala-postgres-reader
```

--------------------------------

### Manual Docker Compose Execution

Source: https://github.com/absmach/magistrala/blob/main/docker/README.md

Starts Magistrala services manually using specific environment files.

```bash
scripts/generate-atom-secrets.sh   # first time only
docker compose -f docker/docker-compose.yaml \
  --env-file docker/.env --env-file docker/.env.tokens up
```

--------------------------------

### Example JSON Output

Source: https://github.com/absmach/magistrala/blob/main/pkg/transformers/json/README.md

The resulting flattened JSON object after transformation, where nested keys are joined with '/'.

```json
{
    "name": "name",
    "id":8659456789564231564,
    "in": 3.145,
    "alarm": true,
    "ts": 1571259850000,
    "d/tmp": 2.564,
    "d/hmd": 87,
    "d/loc/x": 1,
    "d/loc/y": 2
}
```

--------------------------------

### Authenticate with CLI

Source: https://github.com/absmach/magistrala/blob/main/cli/README.md

Log in using standard credentials or tenant-scoped identifiers.

```bash
./build/cli login admin 12345678
```

```bash
./build/cli login user@example.com secret --tenant-id <workspace_id>
./build/cli login user@example.com secret --tenant-alias <workspace_alias>
```

--------------------------------

### Configure SDK Client

Source: https://github.com/absmach/magistrala/blob/main/pkg/sdk/README.md

Defines the configuration structure and initialization function for the SDK client.

```go
type Config struct {
    CertsURL        string
    HTTPAdapterURL  string
    HostURL         string
    BootstrapURL    string
    ReaderURL       string
    AlarmsURL       string
    ReportsURL      string
    RulesEngineURL  string
    MsgContentType  ContentType
    TLSVerification bool
    CurlFlag        bool
    Roles           bool
}

func NewSDK(conf Config) SDK
```

--------------------------------

### Configure instance without Let's Encrypt

Source: https://github.com/absmach/magistrala/blob/main/docker/README.md

Use this command to run the stack with the fallback Nginx certificate instead of Let's Encrypt.

```bash
make run_tls host=example.com letsencrypt=false
```

--------------------------------

### Build the CLI binary

Source: https://github.com/absmach/magistrala/blob/main/cli/README.md

Compile the CLI binary from the project root.

```bash
make cli
```

--------------------------------

### Build Services and Docker Images

Source: https://github.com/absmach/magistrala/blob/main/docker/README.md

Use these commands to compile all services and generate their corresponding Docker images.

```bash
make all        # builds all services
make dockers    # builds all Docker images
```

--------------------------------

### Manage Devices via CLI

Source: https://github.com/absmach/magistrala/blob/main/cli/README.md

Commands for creating, retrieving, updating, and managing the lifecycle of device entities.

```bash
./build/cli devices create <JSON_device> <workspace_id>
./build/cli devices all get <workspace_id>
./build/cli devices <device_id> get
./build/cli devices <device_id> update <JSON_string>
./build/cli devices <device_id> enable
./build/cli devices <device_id> disable
./build/cli devices <device_id> delete
```

--------------------------------

### Reset Atom Schema

Source: https://github.com/absmach/magistrala/blob/main/tools/atom-migration/README.md

Use this command to force a fresh schema installation if the target volume contains an outdated schema.

```bash
make migrate_atom args="--apply --fresh-atom"
```

--------------------------------

### Run Migration as a One-Shot Container

Source: https://github.com/absmach/magistrala/blob/main/tools/atom-migration/README.md

Executes the migration tool directly using the Go toolchain.

```bash
go run ./tools/atom-migration \
  --env docker/.env --from-host \
  --atom-dsn 'host=127.0.0.1 port=5432 user=atom password=atom dbname=atom sslmode=disable'
```

--------------------------------

### NewSDK

Source: https://github.com/absmach/magistrala/blob/main/pkg/sdk/README.md

Initializes a new instance of the Magistrala SDK using the provided configuration.

```APIDOC
## func NewSDK(conf Config) SDK

### Description
Initializes a new SDK instance with the specified configuration settings.

### Parameters
- **conf** (Config) - Required - The configuration object containing URLs and settings for the SDK.
```

--------------------------------

### Update Local Repository

Source: https://github.com/absmach/magistrala/blob/main/CONTRIBUTING.md

Fetch the latest changes from the upstream repository and rebase your local main branch to stay up-to-date. This should be done before starting new work.

```bash
git checkout main
git pull --rebase upstream main
```

--------------------------------

### Configure Network and Run Migration

Source: https://github.com/absmach/magistrala/blob/main/tools/atom-migration/README.md

Commands to bridge the Atom database to the migration network and execute the migration tool.

```bash
docker network connect magistrala-base-net atom-postgres-1
```

```bash
docker run --rm --network magistrala-base-net \
  --user "$(id -u):$(id -g)" \
  -v "$PWD":/work -w /work \
  magistrala/atom-migration:dev \
    --env docker/.env \
    --atom-dsn 'host=atom-postgres-1 port=5432 user=atom password=atom dbname=atom sslmode=disable'
```

--------------------------------

### Request a staging Let's Encrypt certificate

Source: https://github.com/absmach/magistrala/blob/main/docker/README.md

Run this command from the project root to request a staging certificate for the specified host and email.

```bash
make run_tls host=example.com email=admin@example.com
```

--------------------------------

### Create a subscription

Source: https://github.com/absmach/magistrala/blob/main/consumers/notifiers/README.md

Create a new notification subscription by sending a POST request with the topic and contact details.

```bash
curl -X POST http://localhost:9014/subscriptions \
  -H "Authorization: Bearer <your_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "channel/subtopic",
    "contact": "user@example.com"
  }'
```

--------------------------------

### Deploy Bootstrap Service Manually

Source: https://github.com/absmach/magistrala/blob/main/bootstrap/README.md

Commands to clone, compile, and execute the bootstrap service with necessary environment configurations.

```bash
# download the latest version of the service
git clone https://github.com/absmach/magistrala

cd magistrala

# compile the servic e
make bootstrap

# copy binary to bin
make install

# set the environment variables and run the service
MG_BOOTSTRAP_LOG_LEVEL=info \
MG_BOOTSTRAP_DB_HOST=localhost \
MG_BOOTSTRAP_DB_PORT=5432 \
MG_BOOTSTRAP_DB_USER=magistrala \
MG_BOOTSTRAP_DB_PASS=magistrala \
MG_BOOTSTRAP_DB_NAME=bootstrap \
MG_BOOTSTRAP_DB_SSL_MODE=disable \
MG_BOOTSTRAP_DB_SSL_CERT="" \
MG_BOOTSTRAP_DB_SSL_KEY="" \
MG_BOOTSTRAP_DB_SSL_ROOT_CERT="" \
MG_BOOTSTRAP_HTTP_HOST=localhost \
MG_BOOTSTRAP_HTTP_PORT=9010 \
MG_BOOTSTRAP_HTTP_SERVER_CERT="" \
MG_BOOTSTRAP_HTTP_SERVER_KEY="" \
MG_BOOTSTRAP_EVENT_CONSUMER=bootstrap \
MG_ES_URL=nats://localhost:4222 \
ATOM_URL=http://localhost:8080 \
ATOM_SERVICE_TOKEN=<bootstrap-service-token> \
ATOM_JWKS_URL=http://localhost:8080/.well-known/jwks.json \
ATOM_JWT_ISSUER=http://localhost:8080 \
ATOM_JWT_AUDIENCE=magistrala \
ATOM_TIMEOUT=5s \
MG_JAEGER_URL=http://localhost:14268/api/traces \
MG_JAEGER_TRACE_RATIO=1.0 \
MG_SEND_TELEMETRY=true \
MG_BOOTSTRAP_INSTANCE_ID="" \
$GOBIN/magistrala-bootstrap
```

--------------------------------

### Run Auth service locally

Source: https://github.com/absmach/magistrala/blob/main/auth/README.md

Compiles the service and executes the binary with required environment variables for database and server configuration.

```bash
# download the latest version of the service
git clone https://github.com/absmach/magistrala

cd magistrala

# compile the service
make auth

# copy binary to bin
make install

# set the environment variables and run the service
MG_AUTH_LOG_LEVEL=info \
MG_AUTH_DB_HOST=localhost \
MG_AUTH_DB_PORT=5432 \
MG_AUTH_DB_USER=magistrala \
MG_AUTH_DB_PASSWORD=magistrala \
MG_AUTH_DB_NAME=auth \
MG_AUTH_DB_SSL_MODE=disable \
MG_AUTH_DB_SSL_CERT="" \
MG_AUTH_DB_SSL_KEY="" \
MG_AUTH_DB_SSL_ROOT_CERT="" \
MG_AUTH_HTTP_HOST=localhost \
MG_AUTH_HTTP_PORT=8189 \
MG_AUTH_HTTP_SERVER_CERT="" \
MG_AUTH_HTTP_SERVER_KEY="" \
MG_AUTH_GRPC_HOST=localhost \
MG_AUTH_GRPC_PORT=8181 \
MG_AUTH_GRPC_SERVER_CERT="" \
MG_AUTH_GRPC_SERVER_KEY="" \
MG_AUTH_GRPC_SERVER_CA_CERTS="" \
MG_AUTH_GRPC_CLIENT_CA_CERTS="" \
MG_AUTH_SECRET_KEY=secret \
MG_AUTH_ACCESS_TOKEN_DURATION=1h \
MG_AUTH_REFRESH_TOKEN_DURATION=24h \
MG_AUTH_INVITATION_DURATION=168h \
MG_SPICEDB_HOST=localhost \
MG_SPICEDB_PORT=50051 \
MG_SPICEDB_PRE_SHARED_KEY=12345678 \
MG_SPICEDB_SCHEMA_FILE=./docker/spicedb/schema.zed \
MG_JAEGER_URL=http://localhost:14268/api/traces \
MG_JAEGER_TRACE_RATIO=1.0 \
MG_SEND_TELEMETRY=true \
MG_AUTH_ADAPTER_INSTANCE_ID="" \
MG_CALLOUT_URLS="" \
MG_CALLOUT_METHOD="POST" \
MG_CALLOUT_TLS_VERIFICATION=true \
$GOBIN/magistrala-auth
```

--------------------------------

### Manage Device Types via CLI

Source: https://github.com/absmach/magistrala/blob/main/cli/README.md

Commands for creating, updating, and versioning device types, as well as binding devices to specific versions.

```bash
./build/cli devicetypes create <JSON_device_type> <workspace_id>
./build/cli devicetypes all get <workspace_id>
./build/cli devicetypes <device_type_id> update <JSON_string>
./build/cli devicetypes <device_type_id> versions
./build/cli devicetypes <device_type_id> create-version <JSON_version>
./build/cli devicetypes <device_type_id> active-version
./build/cli devicetypes <device_type_id> bind <device_id> [version_id]
```

--------------------------------

### Create Device

Source: https://github.com/absmach/magistrala/blob/main/apidocs/graphql/README.md

Create a new device entity within a tenant.

```graphql
mutation {
  createEntity(input: {
    profileId: "device-profile-id"
    name: "meter-001"
    alias: "meter-001"
    tenantId: "workspace-tenant-id"
  }) {
    id
    kind
    profileId
    name
    alias
    tenantId
  }
}
```

--------------------------------

### Fetch and Import Magistrala Packages

Source: https://github.com/absmach/magistrala/blob/main/pkg/README.md

Commands to retrieve a package via Go modules and import it into a Go source file.

```bash
go get github.com/absmach/magistrala/pkg/authn
```

```go
import "github.com/absmach/magistrala/pkg/authn"
```

--------------------------------

### Manage Channels

Source: https://github.com/absmach/magistrala/blob/main/cli/README.md

Create and list channels associated with specific workspaces.

```bash
./build/cli channels create <workspace_id> "Measurements"
./build/cli channels create <workspace_id> "Alerts" --attributes '{"retention":"7d"}'
./build/cli channels list <workspace_id>
./build/cli channels list <workspace_id> --kind ""
./build/cli channels get <channel_id>
```

--------------------------------

### AddBootstrap

Source: https://github.com/absmach/magistrala/blob/main/pkg/sdk/README.md

Registers a new device configuration for bootstrapping.

```APIDOC
## AddBootstrap

### Description
Registers a new device configuration for bootstrapping within a specific workspace.

### Signature
`smqsdk.AddBootstrap(ctx context.Context, cfg sdk.BootstrapConfig, workspaceID string, token string) (string, error)`

### Parameters
- **ctx** (context.Context) - Execution context
- **cfg** (sdk.BootstrapConfig) - Configuration object containing ExternalID, ExternalKey, Channels, and Name
- **workspaceID** (string) - The ID of the workspace
- **token** (string) - Authentication token
```

--------------------------------

### Report Configuration Methods

Source: https://github.com/absmach/magistrala/blob/main/pkg/sdk/README.md

Methods for managing report configurations, schedules, and templates within the SDK.

```go
AddReportConfig(ctx context.Context, cfg ReportConfig, workspaceID, token string) (ReportConfig, errors.SDKError)
ViewReportConfig(ctx context.Context, id, workspaceID, token string) (ReportConfig, errors.SDKError)
UpdateReportConfig(ctx context.Context, cfg ReportConfig, workspaceID, token string) (ReportConfig, errors.SDKError)
UpdateReportSchedule(ctx context.Context, cfg ReportConfig, workspaceID, token string) (ReportConfig, errors.SDKError)
RemoveReportConfig(ctx context.Context, id, workspaceID, token string) errors.SDKError
ListReportsConfig(ctx context.Context, pm PageMetadata, workspaceID, token string) (ReportConfigPage, errors.SDKError)
EnableReportConfig(ctx context.Context, id, workspaceID, token string) (ReportConfig, errors.SDKError)
DisableReportConfig(ctx context.Context, id, workspaceID, token string) (ReportConfig, errors.SDKError)
GenerateReport(ctx context.Context, config ReportConfig, action ReportAction, workspaceID, token string) (ReportPage, *ReportFile, errors.SDKError)

// Report templates
UpdateReportTemplate(ctx context.Context, cfg ReportConfig, workspaceID, token string) errors.SDKError
ViewReportTemplate(ctx context.Context, id, workspaceID, token string) (ReportTemplate, errors.SDKError)
DeleteReportTemplate(ctx context.Context, id, workspaceID, token string) errors.SDKError
```