1# Conch API Server
3Conch helps you build and manage datacenters.
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
9Conch is open source, licensed under MPL2.
11## Caveat Emptor
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.
20### Operating System Support
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
26### Perl Support
28The API is only certified to run against Perl 5.26.
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.
35* `make run` -- Build the project and run it
36* `make test` -- Run tests
37* `make migrate-db` -- Run database migrations
39#### Needed Packages
41* PostgreSQL 9.6.x
43* Perl, 5.26 or above (e.g. via [perlbrew](https://perlbrew.pl/))
48Copy `conch.conf.dist` to `conch.conf`, modifying for any local parameters,
49including database connectivity information.
51### Starting Conch
53* `make run`
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.
65The 'latest' image is not supported and is rebuilt manually and infrequently.
66*Always* use a release tag.
70The most simple way to get going with the Conch API is to use Docker Compose.
72#### First Run
74Copy `conch.conf.dist` to `conch.conf`, modifying for any local parameters.
75Specifically search for 'docker' in the comments. Ignore the database
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 firstname.lastname@example.org --password kaewee3hipheem8BaiHoo6waed7pha
83docker-compose run --rm web bin/conch-db create-global-workspace
84docker-compose up -d
91# Edit compose file for desired release
93docker-compose up -d postgres
94docker-compose run --rm web bin/conch-db migrate
95docker-compose up -d
98There may be extra commands to run, depending on the specific release. In that
99case, the upgrade will look something like:
103# Edit compose file for desired release
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
114Copyright Joyent, Inc.
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/>.