Skip to content

Commit b08541d

Browse files
author
Gabriel Monroy
committed
docs(readme): first pass at readme
1 parent e6d260a commit b08541d

1 file changed

Lines changed: 179 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 179 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,191 @@
11
# Deis Control Utility
22

3-
`deisctl` is a command-line utility used to operate a Deis cluster.
3+
`deisctl` is a command-line utility used to provision and operate a Deis cluster.
44

5-
## Build
5+
## Installation
66

7+
In order to build and install `deisctl` you will need the following:
8+
9+
* make
10+
* Go 1.3+
11+
* Godeps (install with `go get github.com/tools/godep`)
12+
13+
```console
14+
$ make install
15+
16+
$ deisctl
17+
Usage:
18+
deisctl <command> [<target>...] [options]
19+
```
20+
21+
## Remote Configuration
22+
23+
While `deisctl` can be run locally on a CoreOS host, it is most useful as a tool
24+
for remote administration of a Deis platform. For remote connectivity to work,
25+
you must configure an SSH tunnel to one of your CoreOS hosts.
26+
27+
Test password-less SSH connectivity to a CoreOS host:
28+
29+
```console
30+
$ ssh core@172.17.8.100 hostname
31+
deis-1
32+
```
33+
34+
Export the `DEISCTL_TUNNEL` environment variable:
35+
36+
```console
37+
$ export DEISCTL_TUNNEL=172.17.8.100
738
```
8-
make build
39+
40+
## Provision a Deis Platform
41+
42+
The `deisctl install` command will schedule and activate all of the Deis platform units.
43+
44+
```console
45+
$ deisctl install
46+
47+
Scheduling data containers...
48+
deis-database-data.service: loaded
49+
deis-registry-data.service: loaded
50+
deis-logger-data.service: loaded
51+
deis-builder-data.service: loaded
52+
53+
Activating data containers...
54+
deis-database-data.service: launched
55+
deis-registry-data.service: launched
56+
deis-logger-data.service: launched
57+
deis-builder-data.service: launched
58+
59+
Scheduling units...
60+
deis-database@1.service: loaded
61+
deis-cache@1.service: loaded
62+
deis-logger@1.service: loaded
63+
deis-registry@1.service: loaded
64+
deis-controller@1.service: loaded
65+
deis-builder@1.service: loaded
66+
deis-router@1.service: loaded
67+
68+
Activating units...
69+
deis-logger@1.service: launched
70+
deis-cache@1.service: launched
71+
deis-database@1.service: launched
72+
deis-registry@1.service: launched
73+
deis-controller@1.service: launched
74+
deis-builder@1.service: launched
75+
deis-router@1.service: launched
76+
77+
Done.
78+
```
79+
80+
Note that the default install command activates 1 of each component.
81+
You can install a single component with `deisctl install router`, for example.
82+
83+
You can also use the `deisctl uninstall` command to destroy platform units:
84+
85+
```console
86+
$ deisctl uninstall
87+
Destroyed Unit deis-database@1.service
88+
Destroyed Unit deis-cache@1.service
89+
Destroyed Unit deis-logger@1.service
90+
Destroyed Unit deis-registry@1.service
91+
Destroyed Unit deis-controller@1.service
92+
Destroyed Unit deis-builder@1.service
93+
Destroyed Unit deis-router@1.service
994
```
1095

96+
You can also use `deisctl uninstall router` to uninstall a specific component.
97+
98+
Note that uninstalling platform units will _not_ remove the data units or underlying
99+
data containers. Data must be destroyed manually.
100+
11101
## Usage
12102

13-
### Install Deis
103+
The `deisctl` tool provides a number of other commands, including:
104+
105+
* `deisctl list` - list Deis platform components
106+
* `deisctl status <component>` - retrieve Systemd status of a component
107+
* `deisctl journal <component>` - retrieve Systemd journal output
108+
* `deisctl start <component>` - start a platform component
109+
* `deisctl stop <component>` - stop a platform component
110+
* `deisctl install <component>` - install a single platform component
111+
* `deisctl uninstall <component>` - uninstall a single platform component
112+
* `deisctl scale <component>=<num>` - scale a component to the target number of units
113+
114+
### Examples
14115

116+
```console
117+
$ deisctl list
118+
UNIT MACHINE LOAD ACTIVE SUB
119+
deis-builder-data.service f936b7a5.../172.17.8.100 loaded active exited
120+
deis-builder@1.service f936b7a5.../172.17.8.100 loaded active running
121+
deis-cache@1.service f936b7a5.../172.17.8.100 loaded active running
122+
deis-controller@1.service f936b7a5.../172.17.8.100 loaded active running
123+
deis-database-data.service f936b7a5.../172.17.8.100 loaded active exited
124+
deis-database@1.service f936b7a5.../172.17.8.100 loaded active running
125+
deis-logger-data.service f936b7a5.../172.17.8.100 loaded active exited
126+
deis-logger@1.service f936b7a5.../172.17.8.100 loaded active running
127+
deis-registry-data.service f936b7a5.../172.17.8.100 loaded active exited
128+
deis-registry@1.service f936b7a5.../172.17.8.100 loaded active running
129+
deis-router@1.service f936b7a5.../172.17.8.100 loaded active running
15130
```
16-
deisctl install
131+
132+
```console
133+
$ deisctl status controller
134+
● deis-controller@1.service - deis-controller
135+
Loaded: loaded (/run/fleet/units/deis-controller@1.service; linked-runtime)
136+
Active: active (running) since Mon 2014-08-25 22:56:50 UTC; 15min ago
137+
Process: 22969 ExecStartPre=/bin/sh -c docker inspect deis-controller >/dev/null && docker rm -f deis-controller || true (code=exited, status=0/SUCCESS)
138+
Process: 22945 ExecStartPre=/bin/sh -c IMAGE=`/run/deis/bin/get_image /deis/controller`; docker history $IMAGE >/dev/null || docker pull $IMAGE (code=exited, status=0/SUCCESS)
139+
Main PID: 22979 (sh)
140+
CGroup: /system.slice/system-deis\x2dcontroller.slice/deis-controller@1.service
141+
├─22979 /bin/sh -c IMAGE=`/run/deis/bin/get_image /deis/controller` && docker run --name deis-controller --rm -p 8000:8000 -e PUBLISH=8000 -e HOST=$COREOS_PRIVATE_IPV4 --volumes-from=deis-logger $IMAGE
142+
└─22999 docker run --name deis-controller --rm -p 8000:8000 -e PUBLISH=8000 -e HOST=172.17.8.100 --volumes-from=deis-logger deis/controller:latest
143+
144+
Aug 25 22:57:07 deis-1 sh[22979]: [2014-08-25 16:57:07,959: INFO/MainProcess] Connected to redis://172.17.8.100:6379/0
145+
Aug 25 22:57:07 deis-1 sh[22979]: 2014-08-25 16:57:07 [121] [INFO] Booting worker with pid: 121
146+
Aug 25 22:57:07 deis-1 sh[22979]: [2014-08-25 16:57:07,968: INFO/MainProcess] mingle: searching for neighbors
147+
Aug 25 22:57:08 deis-1 sh[22979]: 2014-08-25 16:57:08 [122] [INFO] Booting worker with pid: 122
148+
Aug 25 22:57:08 deis-1 sh[22979]: 2014-08-25 16:57:08 [123] [INFO] Booting worker with pid: 123
149+
Aug 25 22:57:08 deis-1 sh[22979]: 2014-08-25 16:57:08 [124] [INFO] Booting worker with pid: 124
150+
Aug 25 22:57:08 deis-1 sh[22979]: 2014-08-25 16:57:08 [125] [INFO] Booting worker with pid: 125
151+
Aug 25 22:57:08 deis-1 sh[22979]: 2014-08-25 16:57:08 [126] [INFO] Booting worker with pid: 126
152+
Aug 25 22:57:08 deis-1 sh[22979]: [2014-08-25 16:57:08,979: INFO/MainProcess] mingle: all alone
153+
Aug 25 22:57:08 deis-1 sh[22979]: [2014-08-25 16:57:08,997: WARNING/MainProcess] celery@4378062f17a5 ready.
17154
```
155+
156+
```console
157+
$ deisctl journal controller
158+
...
159+
Aug 25 22:57:08 deis-1 sh[22979]: 2014-08-25 16:57:08 [125] [INFO] Booting worker with pid: 125
160+
Aug 25 22:57:08 deis-1 sh[22979]: 2014-08-25 16:57:08 [126] [INFO] Booting worker with pid: 126
161+
Aug 25 22:57:08 deis-1 sh[22979]: [2014-08-25 16:57:08,979: INFO/MainProcess] mingle: all alone
162+
Aug 25 22:57:08 deis-1 sh[22979]: [2014-08-25 16:57:08,997: WARNING/MainProcess] celery@4378062f17a5 ready.
163+
```
164+
165+
```console
166+
$ deisctl stop controller
167+
deis-controller@1.service: loaded
168+
```
169+
170+
```console
171+
$ deisctl start controller
172+
deis-controller@1.service: launched
173+
```
174+
175+
```console
176+
$ deisctl scale router=2
177+
deis-router@1.service: loaded
178+
deis-router@2.service: loaded
179+
180+
$ deisctl start router
181+
deis-router@1.service: launched
182+
deis-router@2.service: launched
183+
```
184+
185+
## License
186+
187+
Copyright 2014, OpDemand LLC
188+
189+
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at <http://www.apache.org/licenses/LICENSE-2.0>
190+
191+
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

0 commit comments

Comments
 (0)