diff --git a/.llms-snapshots/llms-full.txt b/.llms-snapshots/llms-full.txt index 85df588d..35d633c2 100644 --- a/.llms-snapshots/llms-full.txt +++ b/.llms-snapshots/llms-full.txt @@ -8086,6 +8086,72 @@ You can customize the ports exposed by the emulator: --- +## Collections Configuration + +The `collections` field allows you to define collections for both the Datastore and Storage modules directly in your configuration file. + +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. + +Defining collections in code ensures: + +* Your configuration lives alongside your source code. +* Teams working together share the same environment setup. +* Developers forking or cloning your project can easily get started with a consistent configuration. + +### Datastore + +Use `datastore` field to define the collection of your Datastore. + +#### Example + +juno.config.ts + +``` +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" } ] } }}); +``` + +#### Fields + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `collection` | `string` | ✅ | Name of the collection. Must be unique. | +| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing data. | +| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read documents. | +| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write documents. | +| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. | +| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. | +| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. | +| `maxCapacity` | `number` | ❌ | Max number of documents in the collection. | +| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. | + +### Storage + +Use the `storage` field to define the collection of your Storage. + +#### Example + +juno.config.ts + +``` +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" } ] } }}); +``` + +#### Fields + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `collection` | `string` | ✅ | Name of the collection. Must be unique. | +| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing assets. | +| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read assets. | +| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write assets. | +| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. | +| `maxSize` | `bigint` | ❌ | Maximum size of the collection in bytes. | +| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. | +| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. | +| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. | + +--- + ## Apply Changes 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 [## 📄️ Satellite -Unlike Skylab, the image junobuild/satellite runs a single Satellite in a sandboxed local environment.](/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.](/docs/reference/emulator/satellite.md) [## 📄️ Infrastructure @@ -8452,45 +8518,29 @@ However, in some cases, it may be useful to explicitly reference module IDs. Bel # Satellite -Unlike Skylab, the image [junobuild/satellite](https://hub.docker.com/r/junobuild/satellite) runs a single Satellite in a sandboxed local environment. - -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. - -The CLI watches configuration files and a dedicated `deploy` folder, automatically applying changes and upgrading modules as needed. +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`. --- ## Configuration -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). - -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. +To use this image, your configuration must include the `satellite` field in the `emulator` section. -The definition is as follows: - -``` -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;} -``` +Make also sure to set the `runner` type to match your container runtime, and define the static Satellite ID expected by the image. -### Example - -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: - -juno.dev.config.json +juno.config.ts ``` -{ "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" } ] }} +import { defineConfig } from "@junobuild/config";export default defineConfig({ satellite: { ids: { development: "jx5yt-yyaaa-aaaal-abzbq-cai", production: "" }, source: "dist", predeploy: ["npm run build"] }, emulator: { runner: { type: "docker" }, satellite: {} }}); ``` -### More Options - For more advanced options like customizing ports, image name, or CI setup, see the [Emulator Configuration](/docs/reference/configuration.md#emulator-configuration) section. # Skylab 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: -* ✅ Juno Console (smart contract + UI) +* ✅ Juno Console (backend + UI) * 🛰️ Satellites (support for multiple application containers) * 📊 Orbiter (analytics and tracking module) * ⚙️ Supporting infrastructure (see table below) diff --git a/.llms-snapshots/llms.txt b/.llms-snapshots/llms.txt index a5b34f77..d97b064e 100644 --- a/.llms-snapshots/llms.txt +++ b/.llms-snapshots/llms.txt @@ -127,7 +127,7 @@ Juno is your self-contained serverless platform for building full-stack web apps ## Reference - Emulator - [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. -- [Satellite](https://juno.build/docs/reference/emulator/satellite.md): Unlike Skylab, the image junobuild/satellite runs a single Satellite in a sandboxed local environment. +- [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. - [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: ## Reference - Functions diff --git a/docs/reference/configuration.mdx b/docs/reference/configuration.mdx index 5b85c9e3..9d70ff3f 100644 --- a/docs/reference/configuration.mdx +++ b/docs/reference/configuration.mdx @@ -421,6 +421,118 @@ You can customize the ports exposed by the emulator: --- +## Collections Configuration + +The `collections` field allows you to define collections for both the Datastore and Storage modules directly in your configuration file. + +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. + +Defining collections in code ensures: + +- Your configuration lives alongside your source code. +- Teams working together share the same environment setup. +- Developers forking or cloning your project can easily get started with a consistent configuration. + +### Datastore + +Use `datastore` field to define the collection of your Datastore. + +#### Example + +```ts title="juno.config.ts" +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" + } + ] + } + } +}); +``` + +#### Fields + +| Field | Type | Required | Description | +| -------------------- | ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------- | +| `collection` | `string` | ✅ | Name of the collection. Must be unique. | +| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing data. | +| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read documents. | +| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write documents. | +| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. | +| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. | +| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. | +| `maxCapacity` | `number` | ❌ | Max number of documents in the collection. | +| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. | + +### Storage + +Use the `storage` field to define the collection of your Storage. + +#### Example + +```ts title="juno.config.ts" +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" + } + ] + } + } +}); +``` + +#### Fields + +| Field | Type | Required | Description | +| -------------------- | ----------------------------------------------------------- | -------- | ---------------------------------------------------------------------- | +| `collection` | `string` | ✅ | Name of the collection. Must be unique. | +| `memory` | `"stable"` or `"heap"` | ✅ | Memory type used for storing assets. | +| `read` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can read assets. | +| `write` | `"public"` \| `"private"` \| `"managed"` \| `"controllers"` | ✅ | Who can write assets. | +| `version` | `bigint` | ❌ | Optional. If omitted, the CLI will resolve it and prompt on conflicts. | +| `maxSize` | `bigint` | ❌ | Maximum size of the collection in bytes. | +| `maxChangesPerUser` | `number` | ❌ | Max number of changes (create/update/delete) per user. | +| `maxTokens` | `bigint` | ❌ | Max number of writes and deletes per minute. | +| `mutablePermissions` | `boolean` (default: `true`) | ❌ | Whether permissions can be updated after creation. | + +--- + ## Apply Changes 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. diff --git a/docs/reference/emulator/satellite.md b/docs/reference/emulator/satellite.md index b260b3af..9035c2e4 100644 --- a/docs/reference/emulator/satellite.md +++ b/docs/reference/emulator/satellite.md @@ -1,106 +1,34 @@ # Satellite -Unlike Skylab, the image [junobuild/satellite](https://hub.docker.com/r/junobuild/satellite) runs a single Satellite in a sandboxed local environment. - -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. - -The CLI watches configuration files and a dedicated `deploy` folder, automatically applying changes and upgrading modules as needed. +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`. --- ## Configuration -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). - -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. - -The definition is as follows: - -```typescript -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" ->; +To use this image, your configuration must include the `satellite` field in the `emulator` section. -export interface SatelliteDevCollections { - db?: SatelliteDevDbCollection[]; - storage?: SatelliteDevStorageCollection[]; -} +Make also sure to set the `runner` type to match your container runtime, and define the static Satellite ID expected by the image. -export interface SatelliteDevController { - id: string; - scope: "write" | "admin"; -} +```ts title="juno.config.ts" +import { defineConfig } from "@junobuild/config"; -export interface SatelliteDevConfig { - collections: SatelliteDevCollections; - controllers?: SatelliteDevController[]; -} - -export interface JunoDevConfig { - satellite: SatelliteDevConfig; -} -``` - -### Example - -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: - -```json title="juno.dev.config.json" -{ - "satellite": { - "collections": { - "db": [ - { - "collection": "metadata", - "read": "managed", - "write": "managed", - "memory": "stable", - "mutablePermissions": true - } - ], - "storage": [ - { - "collection": "content", - "read": "public", - "write": "public", - "memory": "stable", - "mutablePermissions": true - } - ] +export default defineConfig({ + satellite: { + ids: { + development: "jx5yt-yyaaa-aaaal-abzbq-cai", + production: "" + }, + source: "dist", + predeploy: ["npm run build"] + }, + emulator: { + runner: { + type: "docker" }, - "controllers": [ - { - "id": "535yc-uxytb-gfk7h-tny7p-vjkoe-i4krp-3qmcl-uqfgr-cpgej-yqtjq-rqe", - "scope": "admin" - } - ] + satellite: {} } -} +}); ``` -### More Options - For more advanced options like customizing ports, image name, or CI setup, see the [Emulator Configuration](../configuration.mdx#emulator-configuration) section. diff --git a/docs/reference/emulator/skylab.md b/docs/reference/emulator/skylab.md index 56626963..02733313 100644 --- a/docs/reference/emulator/skylab.md +++ b/docs/reference/emulator/skylab.md @@ -2,7 +2,7 @@ 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: -- ✅ Juno Console (smart contract + UI) +- ✅ Juno Console (backend + UI) - 🛰️ Satellites (support for multiple application containers) - 📊 Orbiter (analytics and tracking module) - ⚙️ Supporting infrastructure (see table below)