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/Advanced.md
+30-1Lines changed: 30 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,7 +39,36 @@ Deploying using docker compose works almost the same as using a normal docker co
39
39
40
40
Any of the [configuration options](https://docs.traefik.io/configuration/backends/docker/#on-containers) for the default Traefik docker setup can be used.
41
41
42
-
If you have a docker-compose.yml file, __any domain set in exoframe.json will be ignored__.
42
+
If you have a docker-compose.yml file, **any domain set in exoframe.json will be ignored**.
43
+
44
+
For the most part, Exoframe doesn't pass anything from `exoframe.json` to the compose.
45
+
However, one thing that is being passed is environmental variables.
46
+
You can use any variables defined in `exoframe.json` in your compose file.
Exoframe CLI is not particularly demanding and consumes at max ~50mb of RAM.
10
+
Exoframe CLI is not particularly demanding and consumes at max ~50mb of RAM
11
11
Most intensive task from CLI side is packaging the project and streaming that to the server - it doesn't affect RAM usage that much and mostly relies on CPU and network.
12
12
13
13
Running Exoframe server on its own also doesn't require too much resources:
14
14
15
15
- Exoframe Server consumes ~50mb of RAM
16
16
- Traefik started along with server consumes ~60mb of RAM
17
17
18
-
Be aware though - execution of deployments will result in (1) new Docker images being built and (2) new Docker containers being started.
19
-
Depending on your project's complexity, this might require significant amount of resources during both steps resulting in failed deployments (note: if Docker goes out-of-memory during build, you will not get any specific error - just a failed deployment).
18
+
Be aware though - execution of deployments will result in (1) new Docker images being built and (2) new Docker containers being started.
19
+
Depending on your project's complexity, this might require significant amount of resources during both steps resulting in failed deployments (note: if Docker goes out-of-memory during build, you will not get any specific error - just a failed deployment).
20
20
It is recommended to run Exoframe on a server with at least 1GB of RAM.
21
21
22
-
## Supported project types & deployment templates
22
+
## Installation and Basic Usage
23
23
24
-
By default, Exoframe understands and can deploy the following project types:
24
+
To run Exoframe you will need two parts - Exoframe CLI and [Exoframe server](https://github.com/exoframejs/exoframe-server).
25
+
For server install instructions see [Exoframe server repository](https://github.com/exoframejs/exoframe-server).
25
26
26
-
1. Static html based projects - will be deployed using [nginx](http://hub.docker.com/_/nginx) image
27
-
2. Node.js based projects - will be deployed using [node:latest](https://hub.docker.com/_/node) image \*
28
-
3. Docker based project - will be deployed using your [Dockerfile](https://docs.docker.com/engine/reference/builder/)
29
-
4.[Docker-Compose based projects](docs/Advanced.md#Docker-Compose based deployment) - will be deployed using your [docker-compose](https://docs.docker.com/compose/compose-file/) file
27
+
To install Exoframe CLI you can either download one of the pre-packaged binaries from [releases page](https://github.com/exoframejs/exoframe/releases) or install it using npm (needs at least Node 8.x):
30
28
31
-
\* There are two things to keep in mind for Node.js projects: (1) they are started via `npm start`, so make sure you have specified start script in your `package.json`; (2) by default port 80 is exposed, so you need to make your app listen on that port. If you'd like to execute your app in any different way or expose more ports - please use Dockerfile deployment method.
29
+
```
30
+
npm install exoframe -g
31
+
```
32
32
33
-
This list can be extended via deployment templates.
34
-
You can find the list of available templates [on npm](https://www.npmjs.com/search?q=exoframe-template).
35
-
Templates can be installed by executing `exoframe template` command and entering complete template package name.
33
+
Make sure you have [Exoframe server](https://github.com/exoframejs/exoframe-server) deployed, set it as your endpoint using:
36
34
37
-
## Complex recipes
35
+
```
36
+
exoframe endpoint http://you.server.url
37
+
```
38
38
39
-
Exoframe also provides support for third-party complex deployment recipes.
40
-
They allow to quickly and easily deploy complex projects.
39
+
Then login using:
41
40
42
-
For example, you can deploy Wordpress with PHPMyAdmin by simply executing `exoframe setup` and entering [exoframe-recipe-wordpress](https://github.com/exoframejs/exoframe-recipe-wordpress) as desired recipe.
41
+
```
42
+
exoframe login
43
+
```
43
44
44
-
You can find the list of available recipes [on npm](https://www.npmjs.com/search?q=exoframe-recipe).
45
+
Then you will be able to deploy your projects by simply running:
| config | Generate or update project config for current path |
52
-
| list | List currently deployed projects |
53
-
| rm <id> | Remove existing deployment or project |
54
-
| log <id> | Get logs for existing deployment or project |
55
-
| template [ls, rm]| Add, list or remove deployment templates from the server |
56
-
| setup [recipe]| Setup a complex recipe deployment |
57
-
| token [ls, rm]| Generate, list or remove deployment tokens |
58
-
| secret [new, ls, rm]| Create, list or remove deployment secrets |
59
-
| login | Login into Exoframe server |
60
-
| endpoint [url]| Selects or adds the endpoint of Exoframe server |
61
-
| rm-endpoint [url]| Removes an existing endpoint of Exoframe server |
62
-
| update [target]| Gets current versions or updates given target (server, traefik, all) |
63
-
| completion | Generates bash completion script |
51
+
## Updating deployed project
64
52
65
-
## Special commands
53
+
Exoframe provides a way to easily update deployed projects.
54
+
This can be done by passing `--update` (or `-u`) flag to deploy command:
66
55
67
-
Exoframe CLI has a number of special commands, specifically:
56
+
```
57
+
exoframe --update
58
+
```
68
59
69
-
-`exoframe logs exoframe-server` - will return current server logs (only works when running server as container)
60
+
The way it works is quite simple:
61
+
62
+
1. Exoframe deploys new version of the given project
63
+
2. Exoframe then waits for it to start up
64
+
3. Finally, Exoframe removes the old running deployments for given project
65
+
66
+
This can be used together with [deployment tokens](#Deployment-Tokens) to achieve [simple continuous deployment](https://github.com/exoframejs/node-cd-demo) for your projects.
67
+
68
+
## Supported project types & deployment templates
69
+
70
+
By default, Exoframe understands and can deploy the following project types:
71
+
72
+
1. Static html based projects - will be deployed using [nginx](http://hub.docker.com/_/nginx) image
73
+
2. Node.js based projects - will be deployed using [node:latest](https://hub.docker.com/_/node) image \*
74
+
3. Docker based project - will be deployed using your [Dockerfile](https://docs.docker.com/engine/reference/builder/)
75
+
4.[Docker-Compose based projects](docs/Advanced.md#Docker-Compose based deployment) - will be deployed using your [docker-compose](https://docs.docker.com/compose/compose-file/) file
76
+
77
+
\* There are two things to keep in mind for Node.js projects: (1) they are started via `npm start`, so make sure you have specified start script in your `package.json`; (2) by default port 80 is exposed, so you need to make your app listen on that port. If you'd like to execute your app in any different way or expose more ports - please use Dockerfile deployment method.
78
+
79
+
This list can be extended via deployment templates.
80
+
You can find the list of available templates [on npm](https://www.npmjs.com/search?q=exoframe-template).
81
+
Templates can be installed by executing `exoframe template` command and entering complete template package name.
70
82
71
83
## Project config file
72
84
73
-
All of the configuration for the deployed projects is done using `exoframe.json` config file.
74
-
It can either be generated/updated using `exoframe config` (or `exoframe init`) command or created manually.
85
+
All of the configuration for the deployed projects is done using `exoframe.json` config file.
86
+
It can either be generated/updated using `exoframe config` (or `exoframe init`) command or created manually.
75
87
If it doesn't exist during deployment, Exoframe will generate simple config file that only contains name of the current project.
76
88
77
89
Config file has the following structure:
@@ -107,7 +119,7 @@ Config file has the following structure:
107
119
"labels": {
108
120
"my.custom.label":"value"
109
121
},
110
-
// Add additional docker volumes ot your container [optional]
122
+
// Add additional docker volumes to your container [optional]
111
123
// while you can use server paths in sourceVolume place
112
124
// it is recommended to use named volumes
113
125
"volumes": [
@@ -123,6 +135,14 @@ Config file has the following structure:
123
135
// max burst request rate over given time period
124
136
"burst":5,
125
137
},
138
+
// function deployment config
139
+
// see "function deployments" for more info
140
+
"function": {
141
+
// type of function (http, worker, trigger or custom)
142
+
"type":"http",
143
+
// route for HTTP function, [optional] defaults to `/${config.name}`
144
+
"route":"/test"
145
+
},
126
146
// template to be used for project deployment
127
147
// undefined by default, detected by server based on file structure
128
148
"template":"my-template",
@@ -143,50 +163,72 @@ Config file has the following structure:
143
163
144
164
## Project ignore file
145
165
146
-
In some cases you might want to ignore particular files during project deployment (e.g. tests, fixtures, node_modules, etc.).
147
-
You can specify ignored files using `.exoframeignore` file in the root of the project.
148
-
Each line is then used by the [ignore](https://github.com/kaelzhang/node-ignore) module during deployment process.
166
+
In some cases you might want to ignore particular files during project deployment (e.g. tests, fixtures, node_modules, etc.).
167
+
You can specify ignored files using `.exoframeignore` file in the root of the project.
168
+
Each line is then used by the [ignore](https://github.com/kaelzhang/node-ignore) module during deployment process.
149
169
When not provided ignore file contains the following entries:
150
170
151
171
```
152
172
.git
153
173
node_modules
154
174
```
155
175
156
-
## CLI Configuration
176
+
## Complex recipes
177
+
178
+
Exoframe also provides support for third-party complex deployment recipes.
179
+
They allow to quickly and easily deploy complex projects.
180
+
181
+
For example, you can deploy Wordpress with PHPMyAdmin by simply executing `exoframe setup` and entering [exoframe-recipe-wordpress](https://github.com/exoframejs/exoframe-recipe-wordpress) as desired recipe.
182
+
183
+
You can find the list of available recipes [on npm](https://www.npmjs.com/search?q=exoframe-recipe).
184
+
185
+
## Exoframe CLI - Commands
157
186
158
-
Exoframe stores its config in `~/.exoframe/cli.config.yml`.
| config | Generate or update project config for current path |
191
+
| list | List currently deployed projects |
192
+
| rm <id> | Remove existing deployment or project |
193
+
| log <id> | Get logs for existing deployment or project |
194
+
| template [ls, rm]| Add, list or remove deployment templates from the server |
195
+
| setup [recipe]| Setup a complex recipe deployment |
196
+
| token [ls, rm]| Generate, list or remove deployment tokens |
197
+
| secret [new, ls, rm]| Create, list or remove deployment secrets |
198
+
| login | Login into Exoframe server |
199
+
| endpoint [url]| Selects or adds the endpoint of Exoframe server |
200
+
| rm-endpoint [url]| Removes an existing endpoint of Exoframe server |
201
+
| update [target]| Gets current versions or updates given target (server, traefik, all) |
202
+
| completion | Generates bash completion script |
203
+
204
+
## Exoframe CLI - Special Commands
205
+
206
+
Exoframe CLI has a number of special commands, specifically:
207
+
208
+
-`exoframe logs exoframe-server` - will return current server logs (only works when running server as container)
209
+
210
+
## Exoframe CLI - Configuration
211
+
212
+
Exoframe stores its config in `~/.exoframe/cli.config.yml`.
159
213
Currently it contains list of endpoint URLs with associated usernames and authentication tokens:
160
214
161
215
```yaml
162
-
endpoint: "http://localhost:8080"# your endpoint URL, defaults to localhost
216
+
endpoint: 'http://localhost:8080'# your endpoint URL, defaults to localhost
163
217
```
164
218
165
-
## SSH key auth
219
+
## SSH Key-Based Authentication
166
220
167
221
The SSK key needs to be RSA and in PEM format. To ensure your key is generated in a format that works you can generate with this command: `ssh-keygen -t rsa -b 4096 -C "[email protected]" -m 'PEM'`. This follows the [GitHub Instructions](https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/) with an additional flag ensuring it is the right format.
168
222
169
-
## Deployment tokens
223
+
## Deployment Tokens
170
224
171
-
Sometimes you might need to deploy things from environments that don't have your private key (e.g. CI/CD services).
225
+
Sometimes you might need to deploy things from environments that don't have your private key (e.g. CI/CD services).
172
226
For this cases you can use deployment tokens. Here's how it works:
173
227
174
228
1. Make sure you are logged in to your Exoframe server
175
229
2. Generate new deployment token using `exoframe token` command
176
230
3. Use the new token to deploy your service without need to authenticate: `exoframe deploy -t $TOKEN`
177
231
178
-
## Updating deployed project
179
-
180
-
Exoframe provides a way to easily update already deployed projects.
181
-
This can be done by passing `--update` (or `-u`) flag to deploy command.
182
-
The way it works is quite simple:
183
-
184
-
1. Exoframe deploys new version of the given project
185
-
2. Exoframe then waits for them to start up
186
-
3. Exoframe removes the old running deployments for current project
187
-
188
-
This can be used together with deployment tokens to achieve simple continuous deployment for your projects.
189
-
190
-
### Updating the server
232
+
## Updating Exoframe Server
191
233
192
234
The server can simply be updated by invoking `exoframe update server`.
0 commit comments