Few minor points inline, once those are addressed, feel free to push it.
On Tue, Mar 30, 2010 at 10:36 AM, tsedovic@redhat.com wrote:
From: Tomas Sedovic tsedovic@redhat.com
Rename getting_started.txt to README.txt as it's more standard.
Please make this just 'README' rather than 'README.txt'
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/h... ) +* [docs]( http://git.fedorahosted.org/git/?p=deltacloud/docs.git;a=shortlog;h=refs/hea... )
+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/
Please add '--branch next' to the end of the above commands, remove list of steps below, and change this next line to:
The development of the **docs** and **portal** takes place on the `next` branch, so if you want the latest stable release, just remove '--branch next' from the commands above.
+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)
haml just made it in so we can remove this disclaimer ^
+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.
Add line about building gem here as easiest path to get all deps
+
- $ 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]: https://bugzilla.redhat.com/enter_bug.cgi?product=Virtualization%20Tools&...
+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/h... ) -* [docs]( http://git.fedorahosted.org/git/?p=deltacloud/docs.git;a=shortlog;h=refs/hea... )
-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|vinternal 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:
- Run rake db:migrate to create the db file and set it to be owned by
the user who will run the aggregator.
- 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 deltacloud-devel@lists.fedorahosted.org https://fedorahosted.org/mailman/listinfo/deltacloud-devel