xref: /conch/
Name Date Size #Lines LOC

..21-Feb-2019-

bin/H03-May-2019-

dev/H21-Jul-2018-

docker/H27-Apr-2019-

docs/H22-May-2019-

etc/H01-Nov-2018-

json-schema/H17-Jun-2019-

lib/H08-Jun-2019-

misc/H13-Jun-2019-

report/H31-Aug-2018-

smf/H21-Jul-2018-

sql/H08-Jun-2019-

t/H17-Jun-2019-

templates/email/H30-Apr-2019-

.dockerignoreH A D01-Nov-20186 21

.gitattributesH A D06-Dec-201883 43

.mailmapH A D08-Aug-2018438 87

.perlcriticrcH A D21-Jul-201845 21

.perltidyrcH A D21-Jul-201814 43

CODEOWNERSH A D17-Jun-2019588 1614

DockerfileH A D27-Apr-20191.7 KiB6651

Dockerfile.devH A D27-Apr-20191.5 KiB6449

LICENSEH A D27-Apr-201916.3 KiB374293

MakefileH A D22-May-20191.7 KiB6445

README.mdH A D03-May-20193.3 KiB11981

conch.conf.distH A D09-May-20195 KiB132108

cpanfileH A D17-Jun-20193.6 KiB11199

cpanfile.snapshotH A D08-Jun-2019116.8 KiB3,9883,987

docker-compose.ymlH A D27-Apr-20191,009 4843

schema-loader.yamlH A D08-Jun-2019594 3020

README.md

1# Conch API Server
2
3Conch helps you build and manage datacenters.
4
5Conch's goal is to provide an end-to-end solution for full datacenter resource
6lifecycle: from design to initial power-on to end-of-life for all components of
7all devices.
8
9Conch is open source, licensed under MPL2.
10
11## Caveat Emptor
12
13At the time of writing, the API is not considered to be stable. While we do our
14best to prevent breakage, the core is in considerable flux and we do not
15guarantee fit or function right now. The [conch
16shell](https://github.com/joyent/conch-shell) is our current stable interface.
17
18## Installation
19
20### Operating System Support
21
22We currently support SmartOS 17.4 and Docker/Ubuntu. Being a Perl app, the API
23should run most anywhere but the code is only actively tested on SmartOS and
24Docker/Ubuntu.
25
26### Perl Support
27
28The API is only certified to run against Perl 5.26.
29
30### Setup
31
32Below is a list of useful Make commands that can be used to build and run the
33project. All of these should be run in the top level directory.
34
35* `make run` -- Build the project and run it
36* `make test` -- Run tests
37* `make migrate-db` -- Run database migrations
38
39#### Needed Packages
40
41* PostgreSQL 9.6.x
42* Git
43* Perl, 5.26 or above (e.g. via [perlbrew](https://perlbrew.pl/))
44* [Carton](https://metacpan.org/dist/Carton)
45
46#### Configuration
47
48Copy `conch.conf.dist` to `conch.conf`, modifying for any local parameters,
49including database connectivity information.
50
51### Starting Conch
52
53* `make run`
54
55## Docker
56
57### Images
58
59For every release, the Joyent test infrastructure publishes a docker image to
60hub.docker.com . These images are available at
61https://hub.docker.com/r/joyentbuildops/conch-api/tags and it is wise to
62consult the Github release page ( https://github.com/joyent/conch/releases ) to
63determine if the release is a staging or production image.
64
65The 'latest' image is not supported and is rebuilt manually and infrequently.
66*Always* use a release tag.
67
68### Compose
69
70The most simple way to get going with the Conch API is to use Docker Compose.
71
72#### First Run
73
74Copy `conch.conf.dist` to `conch.conf`, modifying for any local parameters.
75Specifically search for 'docker' in the comments. Ignore the database
76parameters.
77
78
79```
80# Edit compose file for desired release
81docker-compose up -d postgres # initialize the postgres database
82docker-compose run --rm web bin/conch-db all --username conch --email conch@example.com --password kaewee3hipheem8BaiHoo6waed7pha
83docker-compose run --rm web bin/conch-db create-global-workspace
84docker-compose up -d
85```
86
87#### Upgrading
88
89```
90docker-compose down
91# Edit compose file for desired release
92docker-compose pull
93docker-compose up -d postgres
94docker-compose run --rm web bin/conch-db migrate
95docker-compose up -d
96```
97
98There may be extra commands to run, depending on the specific release. In that
99case, the upgrade will look something like:
100
101```
102docker-compose down
103# Edit compose file for desired release
104docker-compose pull
105docker-compose up -d postgres
106docker-compose run --rm web bin/conch-db migrate
107docker-compose run --rm web bin/conch upgrade_release_225
108docker-compose up -d
109```
110
111
112## Licensing
113
114Copyright Joyent, Inc.
115
116This Source Code Form is subject to the terms of the Mozilla Public License,
117v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
118one at <http://mozilla.org/MPL/2.0/>.
119