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 10.10
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`
60The most simple way to get going with the Conch API is to use Docker Compose.
64First, build the image locally using `docker/builder.sh`
66#### First Run
68Copy `conch.conf.dist` to `conch.conf`, modifying for any local parameters.
69Specifically search for 'docker' in the comments. Ignore the database
74# Edit compose file for desired release
75docker-compose up -d postgres # initialize the postgres database
76docker-compose run --rm web bin/conch-db all --username conch --email email@example.com --password kaewee3hipheem8BaiHoo6waed7pha
77docker-compose run --rm web bin/conch-db create-global-workspace
78docker-compose up -d
85# Edit compose file for desired release
87docker-compose up -d postgres
88docker-compose run --rm web bin/conch-db migrate
89docker-compose up -d
92There may be extra commands to run, depending on the specific release. In that
93case, the upgrade will look something like:
97# Edit compose file for desired release
99docker-compose up -d postgres
100docker-compose run --rm web bin/conch-db migrate
101docker-compose run --rm web bin/conch upgrade_release_225
102docker-compose up -d
108Copyright Joyent, Inc.
110This Source Code Form is subject to the terms of the Mozilla Public License,
111v.2.0. If a copy of the MPL was not distributed with this file, You can obtain
112one at <http://mozilla.org/MPL/2.0/>.