From: Tomas Sedovic <[email protected]> Rename getting_started.txt to README.txt as it's more standard.
Display the README part in the website's Contribute page. --- README.txt | 163 +++++++++++++++++++++++++ deltacloud.org/content/contribute.haml | 38 ++++++ deltacloud.org/content/contribute.mdown | 38 ------ getting_started.txt | 203 ------------------------------- 4 files changed, 201 insertions(+), 241 deletions(-) create mode 100644 README.txt create mode 100644 deltacloud.org/content/contribute.haml delete mode 100644 deltacloud.org/content/contribute.mdown delete mode 100644 getting_started.txt diff --git a/README.txt b/README.txt new file mode 100644 index 0000000..1c61496 --- /dev/null +++ b/README.txt @@ -0,0 +1,163 @@ +Getting the sources +------------------- +The Deltacloud projects consists of two parts: **Core** and **Aggregator**. Core +gives you the API and drivers to various cloud providers. Aggregator (formerly +known as Portal) is a web frontend to the API. + +In addition, there is the **docs** repository that contains the project +documentation and the sources of the <http://deltacloud.org> website. + +You can browse the code repositories on the web: + +* [core](http://git.fedorahosted.org/git/?p=deltacloud/core.git;a=summary) +* [aggregator](http://git.fedorahosted.org/git/?p=deltacloud/portal.git;a=shortlog;h=refs/heads/next) +* [docs](http://git.fedorahosted.org/git/?p=deltacloud/docs.git;a=shortlog;h=refs/heads/next) + +or download them to your computer: + + $ git clone git://git.fedorahosted.org/git/deltacloud/core.git/ + $ git clone git://git.fedorahosted.org/git/deltacloud/portal.git/ + $ git clone git://git.fedorahosted.org/git/deltacloud/docs.git/ + +The development of the **docs** and **portal** takes place on the `next` branch: + + $ cd path/to/deltacloud/docs + $ git checkout next + $ cd ../portal + $ git checkout next + + +Installing packages +------------------- +In order to make the Deltacloud components work, you'll need to +install at least the following packages (on Fedora 12; your distro's +packages may vary): + + rubygem-rails + rubygem-daemons + rubygem-gettext_rails + rubygem-sqlite3-ruby + rubygem-compass (this is not yet in Fedora, so you'll have to gem install) + rubygem-haml (this is not yet in Fedora, so you'll have to gem install) + +If you want to develop using PostgreSQL database instead of the default SQLite, +install these, too: + + ruby-postgres + postgresql + postgresql-server + +You will also need **deltacloud-client** gem. You can either install the packaged version: + + $ gem install deltacloud-client + +or build it yourself from the **core** repository: + + $ cd core/client + $ gem build deltacloud-client.gemspec + $ gem install deltacloud-client-*.gem + + +Database +-------- +For development purposes we're using [SQLite] database which is much easier to +set up. + +However, we _strongly_ suggest using a more suitable replacement (such as +[PostgreSQL]) in production. + +[SQLite]: http://www.sqlite.org/ +[PostgreSQL]: http://www.postgresql.org/ + +If you want to set up PostgreSQL, read the following section. SQLite users may +skip it and continue with "Setting up the drivers". + + +PostgreSQL database setup +------------------------- +Once you have the proper packages installed you have to setup the +postgresql database. As root: + + # /sbin/service postgresql initdb + # /sbin/service postgresql start + # su - postgres + $ psql + postgres=# CREATE USER dcloud WITH PASSWORD 'v23zj59an' CREATEDB; + postgres=# \q + $ exit + +Now you need to edit the pg_hba.conf file +(`/var/lib/pgsql/data/pg_hba.conf` on Fedora 12): + + local all all trust + host all all 127.0.0.1 255.255.255.255 trust + host all all ::1/128 trust + +If you are running on Fedora 12 *only*, to make rake +succeed you need to append the following to +`/usr/lib/ruby/gems/1.8/gems/activerecord-2.3.4/lib/active_record/connection_adapters/postgresql_adapter.rb`: + + def PGconn.quote_ident(name) + %("#{name}") + end + +(see <http://github.com/mneumann/postgres-pr/issues/unreads#issue/1>) + + +Setting up the drivers +---------------------- +For testing purposes we'll start with the mock driver. Use of the +rest of the drivers should be similar, although may require some +additional gems be installed. + + $ cd path/to/deltacloud/core/server/bin + $ ./deltacloudd -i mock + +This will run the Deltacloud Core server on port 3001. + + +Setting up the Aggregator +------------------------- +Now we need to setup the Aggregator (which includes the UI). +As your user who will run the Aggregator: + + +### With SQLite ### + + $ cd path/to/deltacloud/portal/src/config + $ cp database.sqlite database.yml + +**Note:** you can edit the "database.yml" file to change the location of the +*.sqlite3 database files. + + $ rake db:create:all + $ rake db:migrate + $ cd <wherever you put it>/db + +You should see the "development.sqlite3" file there. Make sure it is owned by +the user who will run the Aggregator. + +### With PostgreSQL ### + + $ cd path/to/deltacloud/portal/src + $ cp database.pg database.yml + $ rake db:create:all + $ rake db:migrate + $ rake db:test:prepare + +If all went well here, then the database should be ready for you +to start up the Aggregator. + +You can now run the UI: + + $ ./script/server + +Which will start up the Aggregator UI on port 3000. + + +Checking out the UI +------------------- +Now that you have all of the components running, you should be able to point +your web browser at <http://localhost:3000> and see the Aggregator page. + +**Happy hacking!** diff --git a/deltacloud.org/content/contribute.haml b/deltacloud.org/content/contribute.haml new file mode 100644 index 0000000..5bbfdfb --- /dev/null +++ b/deltacloud.org/content/contribute.haml @@ -0,0 +1,38 @@ +--- +title: Deltacloud - Contribute +extension: html +filter: + - erb + - markdown + - outline +--- +<toc numbering="off" toc_style="ul" toc_range="h2-h3" /> + +Contribute +========== + +All development of Deltacloud takes place in the open. Communication is run through the mailing list and all source code changes are tracked publicly. We have two lists, one for [user questions][1], and one for [development discussions and patches][2]. + +[1]: https://fedorahosted.org/mailman/listinfo/deltacloud-users +[2]: https://fedorahosted.org/mailman/listinfo/deltacloud-devel + +You can also join us on the Freenode IRC channel #deltacloud. + +Deltacloud developers are generally available on the IRC channel, but if you do not get a response to a posted question on the IRC channel please ask on the [user mailing list][3]. + +[3]: https://fedorahosted.org/mailman/listinfo/deltacloud-users + +We track bugs in [Red Hat Bugzilla][4]. You can [view open bugs][view-bugs] or [file a new one][new-bug] there. + +[4]: https://bugzilla.redhat.com/ +[view-bugs]: https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&component=Deltacloud&product=Virtualization%20Tools&classification=Other +[new-bug]: https://bugzilla.redhat.com/enter_bug.cgi?product=Virtualization%20Tools&component=Deltacloud + +Patches are very welcome. Please send them to the [development list][5]. Patches should be generated with [`git` `format-patch`][6] and sent to the list with [`git` `send-email`][7]. + +[5]: https://fedorahosted.org/mailman/listinfo/deltacloud-devel +[6]: http://kernel.org/pub/software/scm/git/docs/git-format-patch.html +[7]: http://kernel.org/pub/software/scm/git/docs/git-send-email.html + + +<%= File.open('../README.txt').read %> diff --git a/deltacloud.org/content/contribute.mdown b/deltacloud.org/content/contribute.mdown deleted file mode 100644 index 1426b50..0000000 --- a/deltacloud.org/content/contribute.mdown +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Deltacloud - Contribute -extension: html -filter: markdown ---- -Contribute -========== - -All development of Deltacloud takes place in the open. Communication is run through the mailing list and all source code changes are tracked publicly. We have two lists, one for [user questions][1], and one for [development discussions and patches][2]. - -[1]: https://fedorahosted.org/mailman/listinfo/deltacloud-users -[2]: https://fedorahosted.org/mailman/listinfo/deltacloud-devel - -You can also join us on the Freenode IRC channel #deltacloud. - -Deltacloud developers are generally available on the IRC channel, but if you do not get a response to a posted question on the IRC channel please ask on the [user mailing list][3]. - -[3]: https://fedorahosted.org/mailman/listinfo/deltacloud-users - -Bugs are tracked in [here][4] for the time being, though we may move them to Bugzilla at some point. - -[4]: https://fedorahosted.org/deltacloud/report - -If you wish to view the gitweb interface of the various components of Deltacloud, they can be found here: - -* [core](http://git.fedorahosted.org/git/?p=deltacloud/core.git;a=summary) -* [portal](http://git.fedorahosted.org/git/?p=deltacloud/portal.git;a=shortlog;h=refs/heads/next) -* [docs](http://git.fedorahosted.org/git/?p=deltacloud/docs.git;a=shortlog;h=refs/heads/next) - -If you would like to contribute code, this is how you get the component you need: - -* git clone [git://git.fedorahosted.org/git/deltacloud/core.git/](git://git.fedorahosted.org/git/deltacloud/core.git/) -* git clone [git://git.fedorahosted.org/git/deltacloud/portal.git/](git://git.fedorahosted.org/git/deltacloud/portal.git/) -* git clone [git://git.fedorahosted.org/git/deltacloud/docs.git/](git://git.fedorahosted.org/git/deltacloud/docs.git/) - -Patches are very welcome. Please send them to the [development list][5]. Patches should be generated with `git` `format-patch` and sent to the list with `git` `send-email`. - -[5]: https://fedorahosted.org/mailman/listinfo/deltacloud-devel diff --git a/getting_started.txt b/getting_started.txt deleted file mode 100644 index 86ae3a4..0000000 --- a/getting_started.txt +++ /dev/null @@ -1,203 +0,0 @@ -This is a getting started guide for working with Deltacloud. It's -intended for people who want to get deltacloud up and running for -development purposes. If you want to just install and run deltacloud, -please use the packages provided by your distribution. - - -How the deltacloud pieces fit together --------------------------------------- -Deltacloud consists of 4 main pieces: the deltacloud aggregator, the -deltacloud Web User Interface (WUI), the deltacloud drivers, and -the deltacloud API. The architecture loosely looks like the -picture below: - - ############ - ## ## Native API deltacloud -# Cloud # (i.e. EC2) +------------+ API +------------+ -# Provider # <----------> | deltacloud | <----------> | deltacloud | -# (i.e. EC2) # | driver | | API user | - ## ## +------------+ +------------+ - ########### - ^ - | deltacloud API - | - v - internal deltacloud -+------------+ API +------------+ API +------------+ -| deltacloud | <----------> | deltacloud | <----------> | deltacloud | -| WUI | | aggregator | | API user | -+------------+ +------------+ +------------+ - -In words, what the above picture means is that you have one or more -deltacloud drivers running that translate the deltacloud API into -the native API that the backend cloud speaks (if a backend cloud -speaks deltacloud API natively, then this isn't necessary). Once -the driver is in place, then a deltacloud API user can talk to the -backend cloud using the deltacloud API. One of the deltacloud API -users is the deltacloud aggregator, which can be used to aggregate -disparate backend clouds and make business logic decisions about -which particular cloud an instance should start in. The deltacloud -aggregator speaks to the deltacloud WUI, which provides a -user-friendly web user interface for users. The aggregator can -also be accessed via the deltacloud API to support other -user interfaces. - - -Checking out the components ---------------------------- -If you are reading this document, we assume you have already checked -out the docs git repository. Just in case you haven't, you should -check out the following pieces: - -$ git clone git://git.fedorahosted.org/git/deltacloud/core.git/ - - This is the "core" of deltacloud; it includes both the source code - for the deltacloud API, and the various drivers -$ git clone git://git.fedorahosted.org/git/deltacloud/docs.git/ - - Documentation for deltacloud (including this document) -$ git clone git://git.fedorahosted.org/git/deltacloud/portal.git/ - - The deltacloud aggregator code - -Switch the `docs` and `portal` repositories to the "next" branch: - -$ cd docs -$ git checkout -t origin/next -$ cd ../portal -$ git checkout -t origin/next - -This will get you to the latest and greatest stuff. - - -Installing packages -------------------- -In order to make the deltacloud components work, you'll need to -install at least the following packages (on Fedora 12: your distro's -packages may vary): - -rubygem-rails -rubygem-daemons -rubygem-gettext_rails -rubygem-sqlite3-ruby -rubygem-compass (this is not yet in Fedora, so you'll have to gem install) -rubygem-haml (this is not yet in Fedora, so you'll have to gem install) - -If you want to develop using PostgreSQL database instead of the default SQLite, -install these, too: - -ruby-postgres -postgresql -postgresql-server - -You will also need deltacloud-client gem. You can either install the packaged version: - -$ gem itstall deltacloud-client - -or build it yourself from the core.git repository: - -$ cd core/client -$ gem build deltacloud-client.gemspec -$ gem install deltacloud-client-*.gem - - -Database --------- -For development purposes we're using SQLite database which is much easier to -set up. - -However, we _strongly_ suggest using a more suitable replacement (such as -PostgreSQL) in production. - -If you want to set up PostgreSQL, read the following section. SQLite users may -skip it and continue with "Setting up the drivers". - - -PostgreSQL database setup -------------------------- -Once you have the proper packages installed you have to setup the -postgresql database. As root: - -# /sbin/service postgresql initdb -# /sbin/service postgresql start -# su - postgres -$ psql -postgres=# CREATE USER dcloud WITH PASSWORD 'v23zj59an' CREATEDB; -postgres=# \q -$ exit - -Now you need to edit the pg_hba.conf file -(/var/lib/pgsql/data/pg_hba.conf on Fedora 12): - ---------- snip ------------------------------ -local all all trust -host all all 127.0.0.1 255.255.255.255 trust -host all all ::1/128 trust ---------- snip ------------------------------ - -If you are running on Fedora 12 *only*, to make rake -succeed you need to append the following to -/usr/lib/ruby/gems/1.8/gems/activerecord-2.3.4/lib/active_record/connection_adapters/postgresql_adapter.rb: - - def PGconn.quote_ident(name) - %("#{name}") - end - -(see http://github.com/mneumann/postgres-pr/issues/unreads#issue/1) - - -Setting up the drivers ----------------------- -For testing purposes we'll start with the mock driver. Use of the -rest of the drivers should be similar, although may require some -additional gems be installed. - -$ cd path/to/deltacloud/core/server/bin -$ ./deltacloudd -i mock - -This will run the deltacloud core server on port 3001. - - -Setting up the aggregator -------------------------- -Now we need to setup the aggregator (which includes the UI). -As your user who will run the aggregator: - - -For SQLite: - $ cd path/to/deltacloud/portal/src/config - $ cp database.sqlite database.yml - - NOTE: - The .sqlite3 file can be put in any location you desire, - just update the paths in database.yml to point to the correct location. - Also, you will need to take the following 2 steps: - 1. Run rake db:migrate to create the db file and set it to be owned by - the user who will run the aggregator. - 2. Make sure the dir that the above file lives in is also writable by this user. - - $ rake db:create:all - $ rake db:migrate - $ cd <wherever you put it>/db - - You should see the "development.sqlite" file there. - -For PostgreSQL: - $ cd path/to/deltacloud/portal/src - $ cp database.pg database.yml - $ rake db:create:all - $ rake db:migrate - $ rake db:test:prepare - -If all went well here, then the database should be ready for you -to start up the aggregator. - -You can now run the UI: - -$ ./script/server - -Which will start up the aggregator UI on port 3000. - - -Checking out the UI -------------------- -Now that you have all of the components running, you -should be able to point your web browser at localhost:3000 -and see the UI. Happy hacking! -- 1.6.6.1 _______________________________________________ deltacloud-devel mailing list [email protected] https://fedorahosted.org/mailman/listinfo/deltacloud-devel
