You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -6,17 +6,25 @@ description: Set-up the local emulator with Docker
6
6
7
7
# Local Development
8
8
9
-
The tooling is designed with local-first development in mind. Whether you're using the official [plugins](../reference/plugins.md) (Next.js, Vite) or creating a new project with `npm create juno@latest`, local development is the default experience.
9
+
Juno offers something most platforms don’t: a full local development environment that closely mirrors production.
10
10
11
-
When running `npm run dev` (or `start`), your app connects to a locally simulated Satellite via the provided emulator — so you can build and test your backend logic without deploying to the live network.
11
+
When you develop locally, you're running an emulator that includes the well known infrastructure services — including the actual administration Console UI.
12
12
13
-
For continuous integration workflows or advanced setups, this guide shows how to run a Docker-based sandbox that closely mirrors the production environment.
13
+
This enables:
14
+
15
+
- A development experience that mirrors mainnet, helping you build with confidence
16
+
- A smooth dev loop, from prototype to deployment
17
+
- A unique way to build, debug, and validate smart contract logic and frontend behavior — all in one place
18
+
19
+
14
20
15
21
---
16
22
17
23
## Before you begin
18
24
19
-
Make sure you have Docker installed on your machine ([Windows](https://docs.docker.com/desktop/install/windows-install/), [MacOS](https://docs.docker.com/desktop/install/mac-install/), or [Linux](https://docs.docker.com/desktop/install/linux-install/)).
25
+
Docker is used to run a self-contained local environment with all services, replicas, and the Console UI.
26
+
27
+
Make sure the tool is installed on your machine ([Windows](https://docs.docker.com/desktop/install/windows-install/), [MacOS](https://docs.docker.com/desktop/install/mac-install/), or [Linux](https://docs.docker.com/desktop/install/linux-install/)).
20
28
21
29
:::note
22
30
@@ -42,7 +50,7 @@ Then, in your project folder, start the local emulator with:
42
50
juno dev start
43
51
```
44
52
45
-
This will launch a local Satellite along with a local Internet Identity, allowing you to develop and test without deploying anything live.
53
+
This will launch the emulator along with all the services needed to develop your project.
46
54
47
55
We recommend running this in a dedicated terminal window or tab, while your frontend project (e.g. using Vite or Next.js) runs separately using npm run dev or similar.
48
56
@@ -54,6 +62,43 @@ juno dev stop
54
62
55
63
---
56
64
65
+
## Available Images
66
+
67
+
Juno supports two main environments for running your project locally, each tailored to different use cases.
68
+
69
+
| Image | Description | Includes Console UI | Best for |
The default (auto-deployed) Satellite is available with a predefined canister ID `jx5yt-yyaaa-aaaal-abzbq-cai`.
97
+
98
+
:::
99
+
100
+
---
101
+
57
102
## Hot Reload
58
103
59
104
The local container supports live reloading. When you modify your [configuration](#configuration) or build custom [Functions](../build/functions/index.md) to enhance Juno's capabilities with serverless features, those changes will be automatically redeployed.
@@ -68,7 +113,11 @@ Modify the following information of the `docker-compose.yml` file to tweak the c
68
113
69
114
The default port `5987` is used for communication with the locally deployed satellites and other modules in the local environment (replica). This is the primary port for interaction with the application.
70
115
71
-
The container also exposes a small admin server for internal management on port `5999`.
116
+
The container also exposes:
117
+
118
+
- a small admin server for internal management on port `5999`
119
+
120
+
- the Console UI on port `5866`
72
121
73
122
If you want to use a different port, such as 8080, update for example the mapping from `5987:5987` to `8080:5987`, where the first value (8080) is the port you can call, and the second (5987) is the actual container port.
74
123
@@ -80,20 +129,19 @@ The Docker Compose feature automatically creates the volume, so all you need to
80
129
81
130
Naming the volume is particularly useful when developing multiple dApps locally, as it allows you to maintain separate states for each project.
82
131
83
-
Replace `my_dapp` in the configuration with another volume name to suit your needs.
84
-
85
132
For example, if you are developing a "Hello World" project, you could change the volume name to "hello_world".
86
133
87
134
```yml title="docker-compose.yml"
88
135
services:
89
-
juno-satellite:
90
-
image: junobuild/satellite:latest
136
+
juno-skylab:
137
+
image: junobuild/skylab:latest
91
138
ports:
92
139
- 5987:5987
93
140
- 5999:5999
141
+
- 5866:5866
94
142
volumes:
95
143
- hello_world:/juno/.juno # <-------- hello_world modified here
The behavior of the Satellite running in the Docker container can be configured with the help of a local configuration file commonly named `juno.dev.config.json`.
108
-
109
-
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 for your satellite.
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:
The configuration can be placed in a location other than next to the compose file and can be named whatever suits your needs. If you do so, make sure to adapt the compose file accordingly.
201
-
202
-
```yml title="docker-compose.yml"
203
-
services:
204
-
juno-satellite:
205
-
image: junobuild/satellite:latest
206
-
ports:
207
-
- 5987:5987
208
-
- 5999:5999
209
-
volumes:
210
-
- my_dapp:/juno/.juno
211
-
- /your/custom/path/your_config_file.json:/juno/juno.dev.config.json # <-------- Modify location and file name of the left hand part
212
-
213
-
volumes:
214
-
my_dapp:
215
-
```
216
-
217
-
---
218
-
219
153
## Usage
220
154
221
155
During local development, your app connects to the local emulator (container) by default — no extra configuration needed.
@@ -258,6 +192,10 @@ The admin server running on port `5999` provides a variety of internal managemen
258
192
259
193
### Get ICP
260
194
195
+
If you're using the full environment, the Console UI includes a "Get ICP" button in the wallet. It’s a quick way to get ICP out of the box.
196
+
197
+
198
+
261
199
You might want to transfer some ICP from the ledger to a specified principal, which can be particularly useful when you're just getting started developing your app and no users currently own ICP. This can be achieved by querying:
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.
288
-
289
-
However, in some cases, it may be useful to explicitly reference module IDs. Below is a list of the modules and their respective IDs that are automatically mounted.
290
-
291
-
:::note
292
-
293
-
Except for the Satellite ID, which differs from your production environment, all other IDs match the actual smart contract IDs on the mainnet.
If you're using the Docker image intended for developing the Console, you get access to some extra modules that we may eventually merge into the development container. Let us know if you're interested!
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.
4
+
5
+
However, in some cases, it may be useful to explicitly reference module IDs. Below is a list of the modules and their respective IDs that are automatically mounted.
0 commit comments