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
Copy file name to clipboardExpand all lines: docs/content/guides/6.multistore/2.tooling-and-concepts/4.deployment/7.configuration.md
+220-1Lines changed: 220 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -7,11 +7,230 @@ navigation:
7
7
8
8
# Deployment - Configuration
9
9
10
+
Deploying your Alokai stores is incredibly simple! With our powerful deployment system, you can go from development to production in just a few minutes.
11
+
12
+
A single CLI command takes care of everything – it builds the store, optimizes it for deployment, creates a Docker image, pushes it to our repository, and initiates the deployment process on the cluster.
13
+
14
+
Whether you’re managing a single store or orchestrating multiple brands, Alokai’s configuration system makes deployment effortless. This guide will show you how to leverage these capabilities and get your stores up and running with minimal effort.
15
+
16
+
**What You'll Learn**
17
+
18
+
::list{type="success"}
19
+
- Configuring your `alokai.config.json` for successful deployments
20
+
- Choosing and configuring frameworks for your stores
21
+
- Managing multiple store deployments efficiently
22
+
- Running and testing deployments locally
23
+
::
24
+
25
+
## Core Concepts
26
+
27
+
### The `alokai.config.json` File
28
+
29
+
The `alokai.config.json` file is the central configuration file that controls how your stores are deployed. It contains essential settings for:
30
+
- Project identification
31
+
- Deployment regions
32
+
- Framework selection
33
+
- Store-specific configurations
34
+
35
+
Example configuration:
36
+
```json
37
+
{
38
+
"stores": {
39
+
"fashion-brand": {
40
+
"deployment": {
41
+
"projectName": "fashion-brand-prod",
42
+
"region": "us-east-1",
43
+
"framework": "nextjs"
44
+
}
45
+
},
46
+
"sports-brand": {
47
+
"deployment": {
48
+
"projectName": "sports-brand-prod",
49
+
"region": "eu-west-1",
50
+
"framework": "nuxt"
51
+
}
52
+
}
53
+
}
54
+
}
55
+
```
56
+
57
+
::warning Configuration Required
58
+
Each deployable store must have a valid configuration in `alokai.config.json`. Template stores shouldn't be placed in the `alokai.config.json` file as they are not deployed.
59
+
::
60
+
61
+
## Configuration Parameters
62
+
63
+
### `projectName`
64
+
65
+
The `projectName` parameter is a crucial identifier that links your store to Alokai Console.
66
+
67
+
::tip Finding Your Project Name
68
+
You can find your project name in the [Deployment Variables](/console/instance/settings/deployment-variables) section of the Alokai Console.
69
+
::
70
+
71
+
Example configuration:
72
+
```json
73
+
{
74
+
"stores": {
75
+
"fashion-brand": {
76
+
"deployment": {
77
+
"projectName": "fashion-brand-prod", // Must match Alokai Console project name
78
+
// ... other parameters
79
+
}
80
+
}
81
+
}
82
+
}
83
+
```
84
+
85
+
### `region`
86
+
87
+
The `region` parameter determines where your store will be deployed.
88
+
89
+
::warning `region` Required
90
+
Deployment cannot be triggered without a valid region configuration. The `region` value can be found in the [Deployment Variables](/console/instance/settings/deployment-variables) section of the Alokai Console. Ensure the value in `alokai.config.json` matches the region selected for your project.
91
+
::
92
+
93
+
Example region configuration:
94
+
```json
95
+
{
96
+
"stores": {
97
+
"fashion-brand": {
98
+
"deployment": {
99
+
"region": "us-east-1", // AWS region identifier
100
+
// ... other parameters
101
+
}
102
+
}
103
+
}
104
+
}
105
+
```
106
+
107
+
### `framework`
108
+
109
+
::info Auto-detection
110
+
The `framework` parameter is optional when your project uses only one frontend framework (Next.js or Nuxt). In this case, Alokai CLI will automatically detect and use the correct framework.
111
+
::
112
+
113
+
The `framework` parameter defines whether a store uses Next.js or Nuxt. Alokai supports both frameworks out of the box through two base applications:
114
+
-`apps/storefront-unified-nextjs` for Next.js stores
115
+
-`apps/storefront-unified-nuxt` for Nuxt stores
116
+
117
+
Each store in `alokai.config.json` may specify which framework it will use for deployment:
118
+
119
+
```json
120
+
{
121
+
"stores": {
122
+
"fashion-brand": {
123
+
"deployment": {
124
+
"framework": "nextjs", // This store will deploy using Next.js
125
+
// ... other parameters
126
+
}
127
+
},
128
+
"sports-brand": {
129
+
"deployment": {
130
+
"framework": "nuxt", // This store will deploy using Nuxt
131
+
// ... other parameters
132
+
}
133
+
}
134
+
}
135
+
}
136
+
```
137
+
138
+
Your project structure can support both frameworks simultaneously. For example:
139
+
```bash
140
+
apps/
141
+
├── storefront-unified-nextjs/ # Base Next.js implementation
142
+
├── storefront-unified-nuxt/ # Base Nuxt implementation
This dual-framework support is particularly beneficial when:
151
+
- Different teams specialize in different frameworks
152
+
- You're migrating from one framework to another
153
+
- Specific stores have requirements better suited to a particular framework
154
+
155
+
## Local Build & Deployment via CLI
156
+
157
+
::warning Development Environment Only
158
+
Triggering deployments locally should only be used for development and testing purposes. For production deployments, we recommend using CI/CD pipelines (like GitHub Actions, GitLab CI, or Bitbucket Pipelines) as they provide better credentials' security, a controlled deployment environment, version control integration, and automated validation checks. You can read more about it in the [CI/CD guide](/guides/multistore/tooling-and-concepts/ci-cd).
159
+
::
160
+
161
+
### Prerequisites
162
+
163
+
1.**Docker**
164
+
- Docker must be installed and running on your machine
165
+
166
+
2.**Cloud Credentials**
167
+
- Find your credentials in the [Alokai Console](/console/instance/settings/deployment-variables)
168
+
- Use staging/dev environment for triggering deployments locally
169
+
- Set up environment variables or provide them via CLI flags:
- Confirm `region` selection is appropriate for testing
181
+
182
+
### Deployment Command
183
+
184
+
One of the great things about Alokai is how simple it makes deployments! The basic deployment command is:
185
+
186
+
```bash
187
+
yarn store deploy --store-id=fashion-brand \
188
+
--cloud-username=your_username \
189
+
--cloud-password=your_password
190
+
```
191
+
192
+
::tip Environment Variables
193
+
You can simplify the command by using environment variables. The Alokai CLI automatically loads variables from the `.env` file in your project root, which is the recommended approach:
194
+
195
+
```bash
196
+
# .env file in your project root
197
+
CLI_CLOUD_USERNAME=your_username
198
+
CLI_CLOUD_PASSWORD=your_password
199
+
```
200
+
201
+
Alternatively, you can set them manually in your terminal:
202
+
```bash
203
+
export CLI_CLOUD_USERNAME=your_username
204
+
export CLI_CLOUD_PASSWORD=your_password
205
+
```
206
+
207
+
With either approach, you'll only need to specify the store-id:
208
+
```bash
209
+
yarn store deploy --store-id=fashion-brand
210
+
```
211
+
::
212
+
213
+
That's it! The CLI handles all the complexity of building, packaging, and deploying your store. You can also add `--verbose` flag to see detailed logs:
214
+
215
+
```bash
216
+
yarn store deploy --store-id=fashion-brand \
217
+
--verbose # Optional: see detailed deployment logs
218
+
```
219
+
220
+
You can also use the `--all` flag to deploy all deployable stores.
221
+
222
+
::tip Easy Development
223
+
The ability to deploy locally makes development and testing much faster! You can quickly test your changes in a production-like environment without waiting for CI/CD pipelines. If you want to deploy to a different project in console, you can temporarily change the `projectName` in `alokai.config.json`.
224
+
::
225
+
226
+
::danger Credential Security
227
+
For security reasons, you must never commit credentials to version control, share credentials with unauthorized team members or use production credentials for triggering deployments locally. Always prefer using environment variables.
0 commit comments