Skip to content

Commit

Permalink
Merge dae6a23 into 6c86b84
Browse files Browse the repository at this point in the history
  • Loading branch information
@unixcow
unixcow committed May 13, 2019
2 parents 6c86b84 + dae6a23 commit c8b53b2
Show file tree
Hide file tree
Showing 2 changed files with 102 additions and 59 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,4 @@ exoframe-linux
exoframe-macos
exoframe-win.exe
.idea/
.DS_Store
160 changes: 101 additions & 59 deletions docs/Basics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
## Concepts

- **Project** - one or more deployments grouped together (e.g. started via docker-compose)
- **Deployment** - one and only one deployed service
- **Deployment** - one and only one deployed service.

## Requirements

Expand All @@ -12,61 +12,81 @@ Most intensive task from CLI side is packaging the project and streaming that to

Running Exoframe server on its own also doesn't require too much resources:

- Exoframe Server consumes ~50mb of RAM
- Traefik started along with server consumes ~60mb of RAM
- Exoframe Server consumes ~50mb of RAM.
- Traefik started along with server consumes ~60mb of RAM.

Be aware though - execution of deployments will result in (1) new Docker images being built and (2) new Docker containers being started.
Be aware though - execution of deployments will result in new Docker images built, and containers started.
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).
It is recommended to run Exoframe on a server with at least 1GB of RAM.

## Supported project types & deployment templates
## Installation

By default, Exoframe understands and can deploy the following project types:
To run Exoframe you will need two parts - Exoframe CLI and [Exoframe server](https://github.com/exoframejs/exoframe-server).
For server install instructions see [Exoframe server repository](https://github.com/exoframejs/exoframe-server).

1. Static html based projects - will be deployed using [nginx](http://hub.docker.com/_/nginx) image
2. Node.js based projects - will be deployed using [node:latest](https://hub.docker.com/_/node) image \*
3. Docker based project - will be deployed using your [Dockerfile](https://docs.docker.com/engine/reference/builder/)
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
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):

\* 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.
```
npm install exoframe -g
```

This list can be extended via deployment templates.
You can find the list of available templates [on npm](https://www.npmjs.com/search?q=exoframe-template).
Templates can be installed by executing `exoframe template` command and entering complete template package name.
Make sure you have [Exoframe server](https://github.com/exoframejs/exoframe-server) deployed, set it as your endpoint using:

## Complex recipes
```
exoframe endpoint http://you.server.url
```

Exoframe also provides support for third-party complex deployment recipes.
They allow to quickly and easily deploy complex projects.
Then login using:

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.
```
exoframe login
```

You can find the list of available recipes [on npm](https://www.npmjs.com/search?q=exoframe-recipe).
Then you will be able to deploy your projects by simply running:

## Commands
```
exoframe
```

| Command | Description |
| -------------------- | -------------------------------------------------------------------- |
| deploy [path] | Deploy specified path |
| config | Generate or update project config for current path |
| list | List currently deployed projects |
| rm <id> | Remove existing deployment or project |
| log <id> | Get logs for existing deployment or project |
| template [ls, rm] | Add, list or remove deployment templates from the server |
| setup [recipe] | Setup a complex recipe deployment |
| token [ls, rm] | Generate, list or remove deployment tokens |
| secret [new, ls, rm] | Create, list or remove deployment secrets |
| login | Login into Exoframe server |
| endpoint [url] | Selects or adds the endpoint of Exoframe server |
| rm-endpoint [url] | Removes an existing endpoint of Exoframe server |
| update [target] | Gets current versions or updates given target (server, traefik, all) |
| completion | Generates bash completion script |
## Deployment

## Special commands
With Exoframe CLI installed, [Generate an `exoframe.json`](#Project-Config-File) file and run:

Exoframe CLI has a number of special commands, specifically:
```
exoframe
```

- `exoframe logs exoframe-server` - will return current server logs (only works when running server as container)
## Updating deployed project

Exoframe provides a way to easily update deployed projects.
This can be done by passing `--update` (or `-u`) flag to deploy command:

```
exoframe --update
```

The way it works is quite simple:

1. Exoframe deploys new version of the given project.
2. Exoframe then waits for it to start up.
3. Finally, Exoframe removes the old running deployments for given project.

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.

## Supported project types & deployment templates

By default, Exoframe understands and can deploy the following project types:

1. Static html based projects - will be deployed using [nginx](http://hub.docker.com/_/nginx) image.
2. Node.js based projects - will be deployed using [node:latest](https://hub.docker.com/_/node) image. \*
3. Docker based project - will be deployed using your [Dockerfile](https://docs.docker.com/engine/reference/builder/).
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.

\* 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.

This list can be extended via deployment templates.
You can find the list of available templates [on npm](https://www.npmjs.com/search?q=exoframe-template).
Templates can be installed by executing `exoframe template` command and entering complete template package name.

## Project config file

Expand Down Expand Up @@ -107,7 +127,7 @@ Config file has the following structure:
"labels": {
"my.custom.label": "value"
},
// Add additional docker volumes ot your container [optional]
// Add additional docker volumes to your container [optional]
// while you can use server paths in sourceVolume place
// it is recommended to use named volumes
"volumes": [
Expand Down Expand Up @@ -153,40 +173,62 @@ When not provided ignore file contains the following entries:
node_modules
```

## CLI Configuration
## Complex recipes

Exoframe also provides support for third-party complex deployment recipes.
They allow to quickly and easily deploy complex projects.

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.

You can find the list of available recipes [on npm](https://www.npmjs.com/search?q=exoframe-recipe).

## Exoframe CLI - Commands

| Command | Description |
| -------------------- | -------------------------------------------------------------------- |
| deploy [path] | Deploy specified path |
| config | Generate or update project config for current path |
| list | List currently deployed projects |
| rm <id> | Remove existing deployment or project |
| log <id> | Get logs for existing deployment or project |
| template [ls, rm] | Add, list or remove deployment templates from the server |
| setup [recipe] | Setup a complex recipe deployment |
| token [ls, rm] | Generate, list or remove deployment tokens |
| secret [new, ls, rm] | Create, list or remove deployment secrets |
| login | Login into Exoframe server |
| endpoint [url] | Selects or adds the endpoint of Exoframe server |
| rm-endpoint [url] | Removes an existing endpoint of Exoframe server |
| update [target] | Gets current versions or updates given target (server, traefik, all) |
| completion | Generates bash completion script |

## Exoframe CLI - Special Commands

Exoframe CLI has a number of special commands, specifically:

- `exoframe logs exoframe-server` - will return current server logs (only works when running server as container)

## Exoframe CLI - Configuration

Exoframe stores its config in `~/.exoframe/cli.config.yml`.
Currently it contains list of endpoint URLs with associated usernames and authentication tokens:

```yaml
endpoint: "http://localhost:8080" # your endpoint URL, defaults to localhost
endpoint: 'http://localhost:8080' # your endpoint URL, defaults to localhost
```

## SSH key auth
## SSH Key-Based Authentication

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 "your_email@example.com" -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.

## Deployment tokens
## Deployment Tokens

Sometimes you might need to deploy things from environments that don't have your private key (e.g. CI/CD services).
For this cases you can use deployment tokens. Here's how it works:

1. Make sure you are logged in to your Exoframe server
2. Generate new deployment token using `exoframe token` command
1. Make sure you are logged in to your Exoframe server.
2. Generate new deployment token using `exoframe token` command.
3. Use the new token to deploy your service without need to authenticate: `exoframe deploy -t $TOKEN`

## Updating deployed project

Exoframe provides a way to easily update already deployed projects.
This can be done by passing `--update` (or `-u`) flag to deploy command.
The way it works is quite simple:

1. Exoframe deploys new version of the given project
2. Exoframe then waits for them to start up
3. Exoframe removes the old running deployments for current project

This can be used together with deployment tokens to achieve simple continuous deployment for your projects.

### Updating the server
## Updating Exoframe Server

The server can simply be updated by invoking `exoframe update server`.

0 comments on commit c8b53b2

Please sign in to comment.