Skip to content

Commit 11fee72

Browse files
yamalightyamalight
committed
Merge branch 'develop', prepare 4.0.0
2 parents c8c8c49 + 8e366fc commit 11fee72

21 files changed

+2557
-1275
lines changed

‎.eslintrc‎

Lines changed: 7 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,13 @@
11
{
2-
"extends": ["airbnb", "prettier"],
3-
"parserOptions": {
4-
"ecmaVersion": 2017,
5-
"sourceType": "module",
6-
"ecmaFeatures": {
7-
"jsx": true
8-
}
9-
},
2+
"parser": "babel-eslint",
3+
"extends": ["standard", "prettier"],
104
"plugins": ["prettier"],
11-
"env": {
12-
"es6": true,
13-
"node": true
14-
},
155
"rules": {
16-
"arrow-parens": "off",
17-
"object-curly-spacing": ["warn", "never"],
186
"max-len": ["error", 120, 4],
19-
"no-confusing-arrow": "warn",
20-
"no-underscore-dangle": "off",
21-
"comma-dangle": [
22-
"error",
23-
{
24-
"arrays": "always-multiline",
25-
"objects": "always-multiline",
26-
"imports": "always-multiline",
27-
"exports": "always-multiline",
28-
"functions": "ignore"
29-
}
30-
],
31-
"react/jsx-filename-extension": "off",
7+
"camelcase": "off",
8+
"promise/param-names": "off",
9+
"prefer-promise-reject-errors": "off",
10+
"no-control-regex": "off",
3211
"prettier/prettier": [
3312
"error",
3413
{
@@ -37,11 +16,6 @@
3716
"bracketSpacing": false,
3817
"printWidth": 120
3918
}
40-
],
41-
"global-require": "off",
42-
"no-console": "off",
43-
"no-unused-expressions": "off",
44-
"no-param-reassign": "off",
45-
"no-return-assign": "off"
19+
]
4620
}
4721
}

‎CHANGELOG.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,21 @@
1+
# 3.3.0 / 2018-12-13
2+
3+
- Add basic secrets support and docs
4+
5+
# 3.2.0 / 2018-12-10
6+
7+
Additions:
8+
9+
- Added support for basic http auth
10+
11+
Changes:
12+
13+
- Moved server docs to main repo
14+
15+
Fixes:
16+
17+
- Fixed rateLimit field wrong format in config docs
18+
119
# 3.1.1 / 2018-09-19
220

321
- Update npm deploy token for travis

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,11 @@ Exoframe is a self-hosted tool that allows simple one-command deployments using
1515
- SSH key based auth
1616
- Rolling updates
1717
- Deploy tokens (e.g. to deploy from CI)
18+
- Deploy secrets (e.g. to hide sensitive env vars)
1819
- Automated HTTPS setup via letsencrypt \*
1920
- Automated gzip compression \*
2021
- Rate-limit support \*
22+
- Basic HTTP Auth support \*
2123
- Simple access to the logs of deployments
2224
- Docker-compose support
2325
- Multiple deployment endpoints and multi-user support
@@ -74,6 +76,7 @@ You can find a list of all commands and options in the [docs](./docs/README.md).
7476
- [Templates guide](docs/TemplatesGuide.md)
7577
- [Recipes guide](docs/RecipesGuide.md)
7678
- [Using nightly versions](docs/Nightly.md)
79+
- [Using development and debug versions](docs/Development.md)
7780
- [Tutorials, articles, video and related links](docs/Links.md)
7881
- [Change Log](CHANGELOG.md)
7982

‎docs/Advanced.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,48 @@ This will define how many requests (`average`) over given time (`period`) can be
4949
For the example above - an average of 5 requests every 3 seconds is allowed with busts of up to 10 requests.
5050

5151
For more information, see [Traefik rate-limiting docs](https://docs.traefik.io/configuration/commons/#rate-limiting).
52+
53+
## Secrets
54+
55+
Exoframe allows you to create server-side secret values that can be used during service deployments.
56+
To use secrets you first need to create one. This can be done by running:
57+
58+
```
59+
$ exoframe secret new
60+
```
61+
62+
Once you specify the name and value, Exoframe server will create new secret _for your current user_.
63+
After creation the secret can be used in `exoframe.json` config file by using secret name and prefixing it with `@`, like so (in this example the secret was name `my-secret`):
64+
65+
```json
66+
"env": {
67+
"SECRET_KEY": "@my-secret"
68+
},
69+
```
70+
71+
Current caveats:
72+
73+
- Currently secrets only work for environment variables
74+
- Currently secrets work only for normal deployments (any template or recipe that uses `startFromParams` won't have secrets expanded)
75+
76+
## Accessing Exoframe data from within the deployed application
77+
78+
Exoframe provides a set of environment variables that are set on each deployment to allow getting project info and settings.
79+
Currently those are:
80+
81+
```bash
82+
# owner of current deployment
83+
EXOFRAME_USER=admin
84+
# project of current deployment
85+
EXOFRAME_PROJECT=projectName
86+
# full deployment ID
87+
EXOFRAME_DEPLOYMENT=exo-admin-deployName-ID
88+
# host used to expose current deployment (if any)
89+
EXOFRAME_HOST=exo-admin-deployName-ID.baseDomain
90+
```
91+
92+
## Plugins
93+
94+
Exoframe-Server supports extension of core features using plugins.
95+
Plugins are installed and loaded automatically once corresponding config is added to [server configuration](ServerConfiguration.md).
96+
Refer to specific plugins docs to see how to configure them.

‎docs/Basics.md‎

Lines changed: 49 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -45,21 +45,28 @@ You can find the list of available recipes [on npm](https://www.npmjs.com/search
4545

4646
## Commands
4747

48-
| Command | Description |
49-
| ----------------- | -------------------------------------------------------------------- |
50-
| deploy [path] | Deploy specified path |
51-
| 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-
| login | Login into Exoframe server |
59-
| endpoint [url] | Selects or adds the endpoint of Exoframe server |
60-
| rm-endpoint [url] | Removes an existing endpoint of Exoframe server |
61-
| update [target] | Gets current versions or updates given target (server, traefik, all) |
62-
| completion | Generates bash completion script |
48+
| Command | Description |
49+
| -------------------- | -------------------------------------------------------------------- |
50+
| deploy [path] | Deploy specified path |
51+
| 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 |
64+
65+
## Special commands
66+
67+
Exoframe CLI has a number of special commands, specifically:
68+
69+
- `exoframe logs exoframe-server` - will return current server logs (only works when running server as container)
6370

6471
## Project config file
6572

@@ -88,7 +95,9 @@ Config file has the following structure:
8895
// object of key-values for env vars [optional]
8996
// no env vars are assigned by default
9097
"env": {
91-
"ENV_VAR": "123"
98+
"ENV_VAR": "123",
99+
// you can use secrets to hide sensitive values from env vars
100+
"OTHER_VAR": "@my-secret"
92101
},
93102
// internal hostname for container [optional]
94103
// see docker docs for more info
@@ -98,9 +107,15 @@ Config file has the following structure:
98107
"labels": {
99108
"my.custom.label": "value"
100109
},
110+
// Add additional docker volumes ot your container [optional]
111+
// while you can use server paths in sourceVolume place
112+
// it is recommended to use named volumes
113+
"volumes": [
114+
"sourceVolume:/path/in/container"
115+
],
101116
// rate-limit config
102117
// see "advanced topics" for more info
103-
"rate-limit": {
118+
"rateLimit": {
104119
// rate-limit time period
105120
"period": "1s",
106121
// request rate over given time period
@@ -110,7 +125,19 @@ Config file has the following structure:
110125
},
111126
// template to be used for project deployment
112127
// undefined by default, detected by server based on file structure
113-
"template": "my-template"
128+
"template": "my-template",
129+
// image to be used to deploy current project
130+
// this option overrides any other type of deployment and makes
131+
// exoframe deploy project using given image name
132+
"image": "",
133+
// image file to load image from
134+
// exoframe will load given tar file into docker daemon before
135+
// execting image deployment
136+
"imageFile": "",
137+
// basic auth, [optional]
138+
// this field allows you to have basic auth to access your deployed service
139+
// format is in user:pwhash
140+
"basicAuth": "user:$apr1$$9Cv/OMGj$$ZomWQzuQbL.3TRCS81A1g/"
114141
}
115142
```
116143

@@ -135,6 +162,10 @@ Currently it contains list of endpoint URLs with associated usernames and authen
135162
endpoint: 'http://localhost:8080' # your endpoint URL, defaults to localhost
136163
```
137164
165+
## SSH key auth
166+
167+
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+
138169
## Deployment tokens
139170

140171
Sometimes you might need to deploy things from environments that don't have your private key (e.g. CI/CD services).

‎docs/Development.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Using Development and Debug Versions
2+
3+
You might need to run Exoframe CLI and Server in development mode.
4+
There is currently three ways to do so.
5+
They are described in more detail below.
6+
7+
## Using development versions from source
8+
9+
Primary way of running Exoframe CLI and Server in development mode is by using source code available in github.
10+
11+
### Exoframe CLI
12+
13+
Exoframe CLI requires you to have Node.js and yarn installed.
14+
To run Exoframe CLI in development follow this steps:
15+
16+
1. Make sure you don't have `exoframe` installed globally - if you do, remove it
17+
2. Clone the Exoframe CLI repo: `git clone [email protected]:exoframejs/exoframe.git && cd exoframe`
18+
3. Install dependencies: `yarn install`
19+
4. Link Exoframe CLI to your global packages to expose it as a command: `npm link`
20+
5. You can now run `exoframe --version` which should execute your dev version of Exoframe CLI
21+
22+
### Exoframe-Server
23+
24+
Exoframe-Server requires you to have Node.js, yarn, Docker and docker-compose installed.
25+
To run Exoframe-Server in development follow this steps:
26+
27+
1. Clone the Exoframe-Server repo: `git clone [email protected]:exoframejs/exoframe-server.git && cd exoframe-server`
28+
2. Install dependencies: `yarn install`
29+
3. You can now run the server by executing: `yarn start`
30+
4. Point your Exoframe CLI to `http://localhost:8080` to access your server
31+
32+
## Using Exoframe-Server debug version from npm
33+
34+
It is also possible to run Exoframe-Server in development mode by using package available in npm.
35+
Exoframe-Server can be installed by running `npm install -g exoframe-server`.
36+
This will add `exoframe-server` binary to your system - executing it will start Exoframe-Server in development mode.
37+
This way also requires you to have Node.js, yarn, Docker and docker-compose installed.
38+
39+
## Using Exoframe-Server debug version from docker hub
40+
41+
It is also possible to run Exoframe-Server in development mode by using docker image available in docker hub.
42+
Exoframe-Server can be started by running `docker run -v ... exoframe/server:debug` (see [readme](../README.md) for full command).
43+
This will start Exoframe-Server in development mode.
44+
This way requires you to have Docker installed.

‎docs/PluginsGuide.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Plugins guide
2+
3+
Exoframe allows extending the core functionality of Exoframe-Server using third party plugins.
4+
This guide aims to explain basics you need to know to create your own plugins.
5+
If you are looking for plugins usage - please see [Advanced](Advanced.md) part of the docs.
6+
7+
## Basics
8+
9+
Exoframe uses [yarn](https://yarnpkg.com/) to install and remove third-party plugins.
10+
The plugins then are added to Exoframe-Server using Node.js `require()` method.
11+
So, make sure that your plugin's `package.json` has correct `main` attribute.
12+
13+
Your plugins main script needs to export the following variables and methods:
14+
15+
```js
16+
module.exports = {
17+
// plugin default config
18+
config: {
19+
// plugin name
20+
name: 'exoframe-plugin-swarm',
21+
// whether plugin requires exclusive hooks to exoframe methods
22+
// exclusive hooks are the only ones being executed
23+
// make sure you only run ONE exclusive plugin at a time
24+
exclusive: true,
25+
},
26+
27+
/* plugin functions that hook into Exoframe-Server methods */
28+
// server init function hook
29+
// should initialize traefik, setup networks, etc
30+
init,
31+
// exoframe start function hook
32+
// should start a deployment from files
33+
start,
34+
// exoframe startFromParams function hook
35+
// should start a deployment from given set of params
36+
startFromParams,
37+
// exoframe list function hook
38+
// should list currently active deployments
39+
list,
40+
// exoframe logs function hook
41+
// should get logs for a given deployment
42+
logs,
43+
// exoframe remove function hook
44+
// should remove a given deployment
45+
remove,
46+
// exoframe compose template extension
47+
// can affect how docker-compose template is executed
48+
compose,
49+
};
50+
```
51+
52+
## Examples
53+
54+
- [Swarm plugin](https://github.com/exoframejs/exoframe-plugin-swarm)

‎docs/ServerConfiguration.md‎

Lines changed: 11 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
21
## Server Configuration
32

43
Exoframe stores its config in `~/.exoframe/server.config.yml`.
@@ -45,6 +44,16 @@ publicKeysPath: '/path/to/your/public/keys'
4544

4645
# whether Exoframe server whould be running in swarm mode, default "false"
4746
swarm: false
47+
48+
# plugins config
49+
plugins:
50+
# list of plugins that has to be installed and loaded by exoframe-server on startup
51+
install: ['exoframe-plugin-swarm']
52+
# specific plugin config (see plugins docs to know what property they use)
53+
swarm:
54+
enabled: true
4855
```
4956
50-
_Warning:_ Most changes to config are applied immediately. With exception of Letsencrypt config. If you are enabling letsencrypt after Traefik instance has been started, you'll need to remove Traefik and then restart Exoframe server for changes to take effect.
57+
_Warning:_ Most changes to config are applied immediately. With exception of Letsencrypt config and Plugins config.
58+
If you are enabling letsencrypt after Traefik instance has been started, you'll need to remove Traefik and then restart Exoframe server for changes to take effect.
59+
If you are adding plugins after server has been started, you'll need to restart the server so that it can install and load newly added plugins.

‎docs/ServerInstallation.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@ docker run -d \
3636
--label traefik.backend=exoframe-server
3737

3838
# this is used to tell traefik on which domain should Exoframe server be listening
39+
# NOTE: it is important, that it is prefixed with "exoframe", or anything really,
40+
# so that exoframe has its own domain and does not interfere with your
41+
# application's url config.
3942
--label traefik.frontend.rule=Host:exoframe.your-host.com
4043
```
4144

0 commit comments

Comments
 (0)