Skip to content

Commit 3093dba

Browse files
lusergitlusergit
authored
docs: revise intro page (#1384)
Revises the introductory page for the project, displaying - License and version - An overview of the project's functionalities - Entrypoints for APIs, (both admin && tenant) - A guide on how to read documentation Signed-off-by: Luca Zaninotto <luca.zaninotto@secomind.com>
1 parent 6231376 commit 3093dba

4 files changed

Lines changed: 179 additions & 17 deletions

File tree

‎backend/docs/pages/intro/intro.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<!---
2+
Copyright 2026 SECO Mind Srl
3+
4+
SPDX-License-Identifier: Apache-2.0
5+
-->
6+
7+
# Edgehog
8+
9+
![Backend CI](https://github.com/edgehog-device-manager/edgehog/actions/workflows/backend-ci.yaml/badge.svg)
10+
![Frontend CI](https://github.com/edgehog-device-manager/edgehog/actions/workflows/frontend-ci.yaml/badge.svg)
11+
![Coverage](https://img.shields.io/coverallsCoverage/github/edgehog-device-manager/edgehog)
12+
13+
**License:** Apache 2.0 — [apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
14+
15+
An open-source IoT device fleet management platform built on [Astarte](https://github.com/astarte-platform/astarte). Manage hardware, push firmware updates, track device health, and automate deployments — all through a single GraphQL API.
16+
17+
## What Edgehog does
18+
19+
<div class="feature-cards">
20+
<div class="feature-card">
21+
<div class="card-icon" style="background: #e0f5f0;">📡</div>
22+
<h3>Device management</h3>
23+
<p>Register and monitor your entire device fleet. Query real-time status: online/offline state, last-seen IP, cellular connectivity, battery, OS info, and hardware details.</p>
24+
</div>
25+
26+
<div class="feature-card">
27+
<div class="card-icon" style="background: #fff4e0;">🔄</div>
28+
<h3>OTA update campaigns</h3>
29+
<p>Create base image collections and roll out firmware upgrades across device groups using campaigns.</p>
30+
</div>
31+
32+
<div class="feature-card">
33+
<div class="card-icon" style="background: #e8f0ff;">📦</div>
34+
<h3>Container deployments</h3>
35+
<p>Define applications as versioned releases of containers. Deploy, upgrade, start, stop, and delete containerized workloads via deployment campaigns.</p>
36+
</div>
37+
38+
<div class="feature-card">
39+
<div class="card-icon" style="background: #fce8f0;">📊</div>
40+
<h3>Fleet grouping</h3>
41+
<p>Tag devices freely and write selector expressions to form dynamic groups that update automatically.</p>
42+
</div>
43+
44+
<div class="feature-card">
45+
<div class="card-icon" style="background: #eaf3de;">📍</div>
46+
<h3>Geolocation</h3>
47+
<p>Track device position and location data reported from the field. Query per-device position and last-seen coordinates through the API.</p>
48+
</div>
49+
50+
<div class="feature-card">
51+
<div class="card-icon" style="background: #eeedfe;">🔗</div>
52+
<h3>Remote Forwarding</h3>
53+
<p>Request and manage forwarder sessions to tunnel traffic to specific devices for diagnostics and remote access — configurable per tenant.</p>
54+
</div>
55+
</div>
56+
57+
## API reference
58+
59+
### Admin REST APIs
60+
61+
Edgehog admin tasks (i.e., managing tenants) are available through a REST API. It supports creating, updating and deleting tenants
62+
63+
**Endpoint**
64+
65+
```
66+
http://<your-host>/admin-api/v1/
67+
```
68+
69+
Replace `<your-host>` with your Edgehog instance hostname.
70+
71+
**Full API docs** available here: [admin-rest-api](admin-rest-api/)
72+
73+
### Tenant GraphQL APIs
74+
75+
All Edgehog operations are exposed through a **GraphQL API**. It supports queries, mutations, and real-time subscriptions.
76+
77+
**Endpoint**
78+
79+
```
80+
http://<your-host>/tenants/<your-tenant>/api
81+
```
82+
83+
Replace `<your-host>` with your Edgehog instance hostname and `<your-tenant>` with the slug of your tenant.
84+
85+
**Full API docs** available here: [tenant-graphql-api](tenant-graphql-api/)
86+
87+
#### Key resources
88+
89+
| [**Queries**](https://docs.edgehog.io/0.12/tenant-graphql-api/#group-Operations-Queries) | Query your device data. |
90+
| [**Mutations**](https://docs.edgehog.io/0.12/tenant-graphql-api/#group-Operations-Mutations) | Make changes and interact with Edgehog. |
91+
| [**Subscriptions**](https://docs.edgehog.io/0.12/tenant-graphql-api/#group-Operations-Subscriptions) | Subscribe to events as they happen. |
92+
93+
## How to read this documentation
94+
95+
**1. Core concepts**
96+
97+
Before exploring features or the API, read the [Core concepts](core_concepts-1.html) page. It defines the building blocks (**Hardware Types**, **Devices**, **System Models**, **Groups**, and **Selectors**) that all other sections depend on.
98+
99+
**2. Follow the feature guides**
100+
101+
The sidebar organizes topics from setup (hardware types, system models) to operations (OTA updates, campaigns, container deployments). Work through them sequentially: each guide builds on the vocabulary established by the previous one.
102+
103+
**3. Use the API reference for integration work**
104+
105+
The [GraphQL API reference](https://docs.edgehog.io/0.12/tenant-graphql-api/) lists every query, mutation, and subscription with argument types and example payloads. Use it alongside the feature guides when building integrations or automating fleet operations.
106+
107+
**4. Note features marked as planned**
108+
109+
Sections marked with an asterisk (\*) (such as Attributes and Attribute filters) describe functionality planned for a future release. The selector syntax for attributes is already in place, but attribute population is not yet active. Treat these sections as forward reference only.
110+
111+
**5. Download or explore offline**
112+
113+
An ePub version of the full documentation is available at the bottom of any page. A [llms.txt](llms.txt) is also provided for machine-readable consumption.

‎backend/docs/pages/user/intro_user.md‎

Lines changed: 0 additions & 15 deletions
This file was deleted.

‎backend/docs/style/cards.css‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
/*
2+
* This file is part of Edgehog.
3+
*
4+
* Copyright 2026 SECO Mind Srl
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*
18+
* SPDX-License-Identifier: Apache-2.0
19+
*/
20+
21+
.feature-cards {
22+
display: grid;
23+
grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
24+
gap: 1.25rem;
25+
margin: 2rem 0;
26+
}
27+
28+
.feature-card {
29+
background: #ffffff;
30+
border: 1px solid #e8e8e8;
31+
border-radius: 12px;
32+
padding: 1.5rem;
33+
box-shadow: 0 1px 3px rgba(0, 0, 0, 0.06);
34+
}
35+
36+
.feature-card .card-icon {
37+
width: 48px;
38+
height: 48px;
39+
border-radius: 10px;
40+
display: flex;
41+
align-items: center;
42+
justify-content: center;
43+
font-size: 1.5rem;
44+
margin-bottom: 1rem;
45+
}
46+
47+
.feature-card h3 {
48+
font-size: 1rem;
49+
font-weight: 700;
50+
margin: 0 0 0.5rem 0;
51+
color: #1a1a1a;
52+
}
53+
54+
.feature-card p {
55+
font-size: 0.9rem;
56+
color: #555;
57+
line-height: 1.6;
58+
margin: 0;
59+
}

‎backend/mix.exs‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,14 +142,19 @@ defmodule Edgehog.MixProject do
142142
# Add here additional documentation files
143143
defp docs do
144144
[
145-
main: "intro_user",
145+
main: "intro",
146146
logo: "docs/images/logo-favicon.png",
147147
javascript_config_path: "../versions.js",
148148
extras: Path.wildcard("docs/pages/*/*.md"),
149149
filter_modules: ~r/Edgehog/,
150-
assets: %{"docs/images/" => "assets"},
150+
assets: %{"docs/images/" => "assets", "docs/style/" => "style"},
151+
before_closing_head_tag: fn
152+
:html -> ~s(<link rel="stylesheet" href="style/cards.css">)
153+
_ -> ""
154+
end,
151155
api_reference: false,
152156
groups_for_extras: [
157+
Introduction: ~r/intro/,
153158
"User Guide": ~r"/user/",
154159
"OTA Updates": ~r"/ota_updates/",
155160
"Containers management": ~r"/containers/",

0 commit comments

Comments
 (0)