xref: /conch/
Name Date Size #Lines LOC

..21-Feb-2019-

bin/H22-Jun-2019-

dev/H21-Jul-2018-

docker/H27-Apr-2019-

docs/HToday-

etc/H01-Nov-2018-

json-schema/H10-Jul-2019-

lib/H08-Jun-2019-

misc/H22-Jun-2019-

report/H22-Jun-2019-

smf/H21-Jul-2018-

sql/H10-Jul-2019-

t/HToday-

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 D22-Jun-2019647 1715

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 DToday3.3 KiB12081

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

cpanfileH A D10-Jul-20193.7 KiB111100

cpanfile.snapshotH A D10-Jul-2019122.5 KiB4,2194,218

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