Skip to content

Commit ff2646c

Browse files
peterpeterparkergithub-actions[bot]
peterpeterparker
and
github-actions[bot]
authored
docs: collections in juno.config (#488)
* docs: collections in juno.config Signed-off-by: David Dal Busco <david.dalbusco@outlook.com> * 📄 Update LLMs.txt snapshot for PR review * docs: collections in juno.config Signed-off-by: David Dal Busco <david.dalbusco@outlook.com> * 📄 Update LLMs.txt snapshot for PR review * docs: bigint type as in backend Signed-off-by: David Dal Busco <david.dalbusco@outlook.com> * 📄 Update LLMs.txt snapshot for PR review --------- Signed-off-by: David Dal Busco <david.dalbusco@outlook.com> Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
1 parent 4e67701 commit ff2646c

5 files changed

Lines changed: 206 additions & 116 deletions

File tree

‎.llms-snapshots/llms-full.txt‎

Lines changed: 73 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -8086,6 +8086,72 @@ You can customize the ports exposed by the emulator:
80868086

80878087
---
80888088

8089+
## Collections Configuration
8090+
8091+
The `collections` field allows you to define collections for both the Datastore and Storage modules directly in your configuration file.
8092+
8093+
This is useful if you prefer defining access rules in code rather than through the Console UI. It’s especially important when using the [junobuild/satellite](/docs/reference/emulator/satellite.md) image, which runs headlessly and doesn't include the Console UI.
8094+
8095+
Defining collections in code ensures:
8096+
8097+
* Your configuration lives alongside your source code.
8098+
* Teams working together share the same environment setup.
8099+
* Developers forking or cloning your project can easily get started with a consistent configuration.
8100+
8101+
### Datastore
8102+
8103+
Use `datastore` field to define the collection of your Datastore.
8104+
8105+
#### Example
8106+
8107+
juno.config.ts
8108+
8109+
```
8110+
import { defineConfig } from "@junobuild/config";export default defineConfig({ satellite: { ids: { production: "qsgjb-riaaa-aaaaa-aaaga-cai" }, source: "dist", collections: { datastore: [ { collection: "tasks", memory: "stable", read: "managed", write: "managed" }, { collection: "announcements", memory: "stable", read: "public", write: "controllers" } ] } }});
8111+
```
8112+
8113+
#### Fields
8114+
8115+
| Field | Type | Required | Description |
8116+
| --- | --- | --- | --- |
8117+
| `collection` | `string` | ✅ | Name of the collection. Must be unique. |
8118+
| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing data. |
8119+
| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read documents. |
8120+
| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write documents. |
8121+
| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. |
8122+
| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. |
8123+
| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. |
8124+
| `maxCapacity` | `number` | ❌ | Max number of documents in the collection. |
8125+
| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. |
8126+
8127+
### Storage
8128+
8129+
Use the `storage` field to define the collection of your Storage.
8130+
8131+
#### Example
8132+
8133+
juno.config.ts
8134+
8135+
```
8136+
import { defineConfig } from "@junobuild/config";export default defineConfig({ satellite: { ids: { production: "qsgjb-riaaa-aaaaa-aaaga-cai" }, source: "dist", collections: { storage: [ { collection: "images", memory: "stable", read: "managed", write: "managed" }, { collection: "files", memory: "stable", read: "public", write: "managed" } ] } }});
8137+
```
8138+
8139+
#### Fields
8140+
8141+
| Field | Type | Required | Description |
8142+
| --- | --- | --- | --- |
8143+
| `collection` | `string` | ✅ | Name of the collection. Must be unique. |
8144+
| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing assets. |
8145+
| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read assets. |
8146+
| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write assets. |
8147+
| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. |
8148+
| `maxSize` | `bigint` | ❌ | Maximum size of the collection in bytes. |
8149+
| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. |
8150+
| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. |
8151+
| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. |
8152+
8153+
---
8154+
80898155
## Apply Changes
80908156

80918157
Configurations such as above ([storage](#storage)), ([datastore](#datastore)), ([authentication](#authentication)), and ([settings](#settings)) require explicit application to your smart contract as they directly impact its behavior.
@@ -8156,7 +8222,7 @@ The junobuild/skylab image is an all-in-one emulator for local development. It b
81568222

81578223
[## 📄️ Satellite
81588224

8159-
Unlike Skylab, the image junobuild/satellite runs a single Satellite in a sandboxed local environment.](/docs/reference/emulator/satellite.md)
8225+
Unlike Skylab, the image junobuild/satellite runs a single Satellite in a headless environment, without the Console UI. It always mounts the same Satellite, using the fixed ID jx5yt-yyaaa-aaaal-abzbq-cai.](/docs/reference/emulator/satellite.md)
81608226

81618227
[## 📄️ Infrastructure
81628228

@@ -8452,45 +8518,29 @@ However, in some cases, it may be useful to explicitly reference module IDs. Bel
84528518

84538519
# Satellite
84548520

8455-
Unlike Skylab, the image [junobuild/satellite](https://hub.docker.com/r/junobuild/satellite) runs a single Satellite in a sandboxed local environment.
8456-
8457-
You can configure the behavior of Satellite with a specific configuration file to define Datastore and Storage collections, additional administrative access keys, and optional serverless extensions. Like Skylab, it also supports live reloading for these serverless functions through a shared folder.
8458-
8459-
The CLI watches configuration files and a dedicated `deploy` folder, automatically applying changes and upgrading modules as needed.
8521+
Unlike Skylab, the image [junobuild/satellite](https://hub.docker.com/r/junobuild/satellite) runs a single Satellite in a headless environment, without the Console UI. It always mounts the same Satellite, using the fixed ID `jx5yt-yyaaa-aaaal-abzbq-cai`.
84608522

84618523
---
84628524

84638525
## Configuration
84648526

8465-
The behavior of the Satellite running in a container can be configured with the help of a local configuration file commonly named `juno.dev.config.ts` (or JavaScript or JSON).
8466-
8467-
This configuration file enables you to define the collections of the Datastore and Storage that run locally, but it also allows for defining additional controllers - i.e. administrative access keys - for your satellite.
8527+
To use this image, your configuration must include the `satellite` field in the `emulator` section.
84688528

8469-
The definition is as follows:
8470-
8471-
```
8472-
export type PermissionText = "public" | "private" | "managed" | "controllers";export type MemoryText = "heap" | "stable";export type RulesType = "db" | "storage";export interface Rule { collection: string; read: PermissionText; write: PermissionText; memory: MemoryText; createdAt?: bigint; updatedAt?: bigint; maxSize?: number; maxCapacity?: number; mutablePermissions: boolean; maxTokens?: number;}export type SatelliteDevDbCollection = Omit< Rule, "createdAt" | "updatedAt" | "maxSize">;export type SatelliteDevStorageCollection = Omit< Rule, "createdAt" | "updatedAt" | "maxCapacity">;export interface SatelliteDevCollections { db?: SatelliteDevDbCollection[]; storage?: SatelliteDevStorageCollection[];}export interface SatelliteDevController { id: string; scope: "write" | "admin";}export interface SatelliteDevConfig { collections: SatelliteDevCollections; controllers?: SatelliteDevController[];}export interface JunoDevConfig { satellite: SatelliteDevConfig;}
8473-
```
8529+
Make also sure to set the `runner` type to match your container runtime, and define the static Satellite ID expected by the image.
84748530

8475-
### Example
8476-
8477-
If, for example, we want to configure a "metadata" collection in the Datastore, a "content" collection in the Storage, and provide an additional controller, we could use the following configuration:
8478-
8479-
juno.dev.config.json
8531+
juno.config.ts
84808532

84818533
```
8482-
{ "satellite": { "collections": { "db": [ { "collection": "metadata", "read": "managed", "write": "managed", "memory": "stable", "mutablePermissions": true } ], "storage": [ { "collection": "content", "read": "public", "write": "public", "memory": "stable", "mutablePermissions": true } ] }, "controllers": [ { "id": "535yc-uxytb-gfk7h-tny7p-vjkoe-i4krp-3qmcl-uqfgr-cpgej-yqtjq-rqe", "scope": "admin" } ] }}
8534+
import { defineConfig } from "@junobuild/config";export default defineConfig({ satellite: { ids: { development: "jx5yt-yyaaa-aaaal-abzbq-cai", production: "<PROD_SATELLITE_ID>" }, source: "dist", predeploy: ["npm run build"] }, emulator: { runner: { type: "docker" }, satellite: {} }});
84838535
```
84848536

8485-
### More Options
8486-
84878537
For more advanced options like customizing ports, image name, or CI setup, see the [Emulator Configuration](/docs/reference/configuration.md#emulator-configuration) section.
84888538

84898539
# Skylab
84908540

84918541
The [junobuild/skylab](https://hub.docker.com/r/junobuild/skylab) image is an all-in-one emulator for local development. It bundles everything you need to build, test, and explore the Juno ecosystem:
84928542

8493-
* ✅ Juno Console (smart contract + UI)
8543+
* ✅ Juno Console (backend + UI)
84948544
* 🛰️ Satellites (support for multiple application containers)
84958545
* 📊 Orbiter (analytics and tracking module)
84968546
* ⚙️ Supporting infrastructure (see table below)

‎.llms-snapshots/llms.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -127,7 +127,7 @@ Juno is your self-contained serverless platform for building full-stack web apps
127127
## Reference - Emulator
128128

129129
- [Infrastructure](https://juno.build/docs/reference/emulator/infrastructure.md): In the local environment, several modules (also known as "canisters" on the Internet Computer) are automatically spun up. This ensures that developers have everything they need to start building right out of the box. Thanks to built-in plugins and tooling, these modules are automatically integrated into the environment, eliminating the need for devs to manually manage their bindings.
130-
- [Satellite](https://juno.build/docs/reference/emulator/satellite.md): Unlike Skylab, the image junobuild/satellite runs a single Satellite in a sandboxed local environment.
130+
- [Satellite](https://juno.build/docs/reference/emulator/satellite.md): Unlike Skylab, the image junobuild/satellite runs a single Satellite in a headless environment, without the Console UI. It always mounts the same Satellite, using the fixed ID jx5yt-yyaaa-aaaal-abzbq-cai.
131131
- [Skylab](https://juno.build/docs/reference/emulator/skylab.md): The junobuild/skylab image is an all-in-one emulator for local development. It bundles everything you need to build, test, and explore the Juno ecosystem:
132132

133133
## Reference - Functions

‎docs/reference/configuration.mdx‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -421,6 +421,118 @@ You can customize the ports exposed by the emulator:
421421

422422
---
423423

424+
## Collections Configuration
425+
426+
The `collections` field allows you to define collections for both the Datastore and Storage modules directly in your configuration file.
427+
428+
This is useful if you prefer defining access rules in code rather than through the Console UI. It’s especially important when using the [junobuild/satellite](./emulator/satellite.md) image, which runs headlessly and doesn't include the Console UI.
429+
430+
Defining collections in code ensures:
431+
432+
- Your configuration lives alongside your source code.
433+
- Teams working together share the same environment setup.
434+
- Developers forking or cloning your project can easily get started with a consistent configuration.
435+
436+
### Datastore
437+
438+
Use `datastore` field to define the collection of your Datastore.
439+
440+
#### Example
441+
442+
```ts title="juno.config.ts"
443+
import { defineConfig } from "@junobuild/config";
444+
445+
export default defineConfig({
446+
satellite: {
447+
ids: {
448+
production: "qsgjb-riaaa-aaaaa-aaaga-cai"
449+
},
450+
source: "dist",
451+
collections: {
452+
datastore: [
453+
{
454+
collection: "tasks",
455+
memory: "stable",
456+
read: "managed",
457+
write: "managed"
458+
},
459+
{
460+
collection: "announcements",
461+
memory: "stable",
462+
read: "public",
463+
write: "controllers"
464+
}
465+
]
466+
}
467+
}
468+
});
469+
```
470+
471+
#### Fields
472+
473+
| Field | Type | Required | Description |
474+
| -------------------- | ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
475+
| `collection` | `string` | ✅ | Name of the collection. Must be unique. |
476+
| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing data. |
477+
| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read documents. |
478+
| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write documents. |
479+
| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. |
480+
| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. |
481+
| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. |
482+
| `maxCapacity` | `number` | ❌ | Max number of documents in the collection. |
483+
| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. |
484+
485+
### Storage
486+
487+
Use the `storage` field to define the collection of your Storage.
488+
489+
#### Example
490+
491+
```ts title="juno.config.ts"
492+
import { defineConfig } from "@junobuild/config";
493+
494+
export default defineConfig({
495+
satellite: {
496+
ids: {
497+
production: "qsgjb-riaaa-aaaaa-aaaga-cai"
498+
},
499+
source: "dist",
500+
collections: {
501+
storage: [
502+
{
503+
collection: "images",
504+
memory: "stable",
505+
read: "managed",
506+
write: "managed"
507+
},
508+
{
509+
collection: "files",
510+
memory: "stable",
511+
read: "public",
512+
write: "managed"
513+
}
514+
]
515+
}
516+
}
517+
});
518+
```
519+
520+
#### Fields
521+
522+
| Field | Type | Required | Description |
523+
| -------------------- | ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------- |
524+
| `collection` | `string` | ✅ | Name of the collection. Must be unique. |
525+
| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing assets. |
526+
| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read assets. |
527+
| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write assets. |
528+
| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. |
529+
| `maxSize` | `bigint` | ❌ | Maximum size of the collection in bytes. |
530+
| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. |
531+
| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. |
532+
| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. |
533+
534+
---
535+
424536
## Apply Changes
425537

426538
Configurations such as above [storage](#storage), [datastore](#datastore), [authentication](#authentication), and [settings](#settings) require explicit application to your smart contract as they directly impact its behavior.

0 commit comments

Comments
 (0)