README.md in forj-1.0.13 vs README.md in forj-1.0.14

- old
+ new

@@ -3,10 +3,12 @@ Installation ------------ +Forj cli supports Ruby 1.9.3 or higher. + ###Fedora/CentOS/Redhat rpm like package system **For ruby 2.0** $ sudo yum install ruby-devel libxml2-devel libxslt-devel python-yaml gcc git -y @@ -15,25 +17,13 @@ ###Ubuntu/Debian deb like package system **For ruby 1.9** $ apt-get -y update - $ sudo apt-get install ruby1.9.1 ruby1.9.1-dev rubygems1.9.1 build-essential libopenssl-ruby1.9.1 libssl-dev zlib1g-dev libxml2-dev libxslt-dev git -y + $ sudo apt-get install ruby1.9.3 ruby1.9.3-dev rubygems1.9.3 build-essential libopenssl-ruby1.9.3 libssl-dev zlib1g-dev libxml2-dev libxslt-dev git -y $ sudo gem install forj - -**For ruby 1.8** - - $ sudo apt-get install ruby1.8-dev ruby1.8 ri1.8 rdoc1.8 irb1.8 rubygems -y - $ sudo apt-get install libreadline-ruby1.8 libruby1.8 libopenssl-ruby -y - $ sudo apt-get install libxslt-dev libxml2-dev -y - $ sudo gem install nokogiri - $ sudo apt-get install ruby-bundler -y - $ sudo gem install mime-types -v 1.25.1 - $ sudo gem install hpcloud - $ sudo gem install forj - **Installation from source** Perform one of the ruby installation steps without `gem install forj`. $ sudo apt-get -y install build-essential make libxslt-dev libxml2-dev $ sudo mkdir -p /opt/config/production/git @@ -91,17 +81,12 @@ `$ forj boot <blueprint> <InstanceName>` Ex: `forj boot redstone myforge` - This command will start a Redstone forge named 'myforge' with the default FORJ account. Previous, we set it to be MyAccount. -NOTE: If you are creating a Forge in a corporate network, a proxy may be required for Maestro to access internet. -You can ask `forj` cli to send the proxy to use with -e +NOTE: If you are creating a Forge in a corporate network, a proxy may be required. See section [Commmon issues] -Ex: Thanks to a CorporateAccount setup with forj setup, the following will use it and set the webproxy metadata. - - `forj boot redstone myforge -a CorporateAccount -e webproxy=$http_proxy` - ###Forj options: To get forj cli help, just type: $ forj @@ -121,79 +106,99 @@ forj ssh #### Configuration -While building your forge, forj needs to load some data by default. Those are listed in the application. +When you create a new forj (`forj boot`), forj cli will load data from several layers of configuration: -You can show them with : +1. Cloud account setting (`forj setup [account]` or `forj get -a <account>` list identified by 'account' origin) +2. Local configuration (`forj get` list identified by 'local' origin) +3. Application defaults and cloud model. (`forj get` list identified by 'forj_core' or 'default') - $ forj show defaults +You can get a complete list of current values: + $ forj get +or + + $ forj get -a <account> + If you need to change one of them: - $ forj set "keypair_name=MyKeypairName" + $ forj set "security_group=test" +or -ex: - forj set keypair_name=nova + $ forj set "security_group=mysec" -a <account> -You can check what kind of value, forj will use to boot/access your forge: +#### Connect to servers - $ forj get -a dev +To ssh into a server + $ forj ssh <name> [node] +e.g. -#### Your config.yaml + $ forj ssh myforge review # review is one node from redstone blueprint -The following list gives you some details about keys/values required to boot/access your forge. +Commmon issues +============== +Certificate Authorities +----------------------- -~/.forj/config.yaml: +If your company certify your server with a private certificate authorities service, you may need to do the following: - default: - account_name: name # Default forj account used to connect to your cloud. This setting is automatically set to the first account created with forj setup <CloudProvider> - maestro_url: url # Maestro GIT repository for clone. - infra_repo: path # Path to the default Infra repository used to store your specific bootstrap/build environment. By default: ~/.forj/infra - image: imageName # Image used to create Maestro and all forge boxes. By default, it is 'Ubuntu Precise 12.04.4 LTS Server 64-bit 20140414 (Rescue Image)' - # If you have created the generic proto2b image, you can set it here. - flavor: flavorName # Maestro Flavor name. This flavor is for Maestro only. Your blueprint layout defines each node flavors on needs. - # By default: standard.medium - bp_flavor: flavorName # Blueprint nodes default flavor. Usually, blueprint node are smaller than Maestro. - # By default: standard.small - ports: [Port1,Port2,...] # list of additional ports to add in your cloud security group. - # This list is added to the default one in defaults.yaml - keypair_path: path # Define the file path to your OpenSSH private key. Useful to access your box with ssh command line. - # By default. ~/.ssh/forj-id_rsa - keypair_name: name # keypair name defined in your cloud to access your server. By default we named it 'forj'. If it doesn't exist, it will be created. - router: name # Router name used by your forge boxes will use to access internet. - security_group: name # Security group name to configure and attach to each forge boxes. - network: name # Network name to attach to each forge boxes. By default we use 'private'. If it doesn't exist, it will be created. - # Internal use. - build_config: name # forj cli use 'build.sh' to create Maestro. See build_config option on build.sh to get more information. By default 'box' - branch: name # forj cli use 'build.sh' to create Maestro. See gitbranch option on build.sh to get more information. By default 'master' - box_name: maestro # forj cli use 'build.sh' to create Maestro. See box_name option on build.sh to get more information. By default 'maestro' +Either your workstation and your cloud may needs to be configured with this CA certificate. -To ssh into a server +* From your workstation: - forj ssh <name> <node> - e.g. forj ssh maestro_01 [maestro, ci, util, review] # the nodes from your blueprint + You can instantly provide the CA certificate to forj cli, with SSL_CERT_FILE env variable<BR> + ex: -Excon and SSL Issue -=================== + SSL_CERT_FILE=~/tmp/cacert.crt forj boot redstone [...] -If you are connecting to a private cloud, you may need to provide some additional certificate data: + OR<BR> -Excon env variables: -* SSL_CERT_DIR : path_to_certs -* SSL_CERT_FILE: path_to_file + You can install this certificate in your workstation. This case depends on your OS.<BR> + typical case: -Ex: + * debian like system: + - cp file to /usr/share/ca-certificates/ + - Update /etc/ca-certificates.conf + - call update-ca-certificates + * rpm like system: + - cp file to /etc/pki/ca-trust/source/anchors/ + - call update-ca-trust extract - export SSL_CERT_FILE=~/ca.crt - forj setup myAccount openstack +* In your cloud: -or + If your cloud is NOT preconfigured (images) with your Company CA certificate, + you can call forj cli with --ca-root-cert at boot time, to configure your boxes with this missing certificate. - SSL_CERT_FILE=~/ca.crt forj setup myAccount openstack + ex: + + forj boot redstone myforge --ca-root-cert ~/tmp/cacert.crt + + You can ask server in your cloud to install it in specific path and file name + + forj boot redstone myforge --ca-root-cert '~/tmp/cacert-2015-1.crt#mycompany/cacrt.crt' + + You can also pre-configure your forj account with this certificate. + + forj set ca-root-cert=~/tmp/cacert-2015-1.crt -a myaccount + or + + forj set 'ca-root-cert=~/tmp/cacert-2015-1.crt#mycompany/cacrt.crt' -a myaccount + +HTTP/HTTPS proxy +---------------- + +If your cloud is NOT preconfigured (images) with your Company proxy setting, +you can ask forj cli to configure your server with the Proxy setting needed. + + +Ex: boot a redstone 'myforge' with a proxy setting. + + $ forj boot redstone myforge -a CorporateAccount -e webproxy=$http_proxy + Contributing to Forj ===================== We welcome all types of contributions. Checkout our website (http://docs.forj.io/en/latest/dev/contribute.html) to start hacking on Forj. Also join us in our community (https://www.forj.io/community/) to help grow and foster Forj for