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[More documentation can be found here.](https://joyent.github.io/conch/)
13## Caveat Emptor
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.
21### Operating System Support
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
27### Perl Support
29The API is only certified to run against Perl 5.26.
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.
36* `make run` -- Build the project and run it
37* `make test` -- Run tests
38* `make migrate-db` -- Run database migrations
40#### Needed Packages
42* PostgreSQL 9.6.x
44* Perl, 5.26 or above (e.g. via [perlbrew](https://perlbrew.pl/))
49Copy `conch.conf.dist` to `conch.conf`, modifying for any local parameters,
50including database connectivity information.
52### Starting Conch
54* `make run`
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.
66The 'latest' image is not supported and is rebuilt manually and infrequently.
67*Always* use a release tag.
71The most simple way to get going with the Conch API is to use Docker Compose.
73#### First Run
75Copy `conch.conf.dist` to `conch.conf`, modifying for any local parameters.
76Specifically search for 'docker' in the comments. Ignore the database
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 email@example.com --password kaewee3hipheem8BaiHoo6waed7pha
84docker-compose run --rm web bin/conch-db create-global-workspace
85docker-compose up -d
92# Edit compose file for desired release
94docker-compose up -d postgres
95docker-compose run --rm web bin/conch-db migrate
96docker-compose up -d
99There may be extra commands to run, depending on the specific release. In that
100case, the upgrade will look something like:
104# Edit compose file for desired release
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
115Copyright Joyent, Inc.
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/>.