Produced by Araxis Merge on 12/14/2017 1:28:07 PM Eastern Standard Time. See www.araxis.com for information about Merge. This report uses XHTML and CSS2, and is best viewed with a modern standards-compliant browser. For optimum results when printing this report, use landscape orientation and enable printing of background images and colours in your browser.
| # | Location | File | Last Modified |
|---|---|---|---|
| 1 | CUI-CPP-v2.3.2-source.zip\doc | using_docker.md | Mon Nov 20 23:19:07 2017 UTC |
| 2 | CUI-CPP-v2.3.2-source.zip\doc | using_docker.md | Thu Dec 14 15:26:27 2017 UTC |
| Description | Between Files 1 and 2 |
|
|---|---|---|
| Text Blocks | Lines | |
| Unchanged | 4 | 348 |
| Changed | 3 | 6 |
| Inserted | 0 | 0 |
| Removed | 0 | 0 |
| Whitespace | |
|---|---|
| Character case | Differences in character case are significant |
| Line endings | Differences in line endings (CR and LF characters) are ignored |
| CR/LF characters | Not shown in the comparison detail |
No regular expressions were active.
| 1 | # Using Do cker | |
| 2 | ||
| 3 | The docker technilog y stack wa s chosen t o support the deploy ment of th is applica tion withi n the | |
| 4 | Amazon Web Services (AWS) EC2 cloud serv ice which is the imp lementatio n technolo gy behind the GocClo ud system. | |
| 5 | ||
| 6 | This appli cation sto res its do cker relat ed configu ration fil es in the config/doc ker direct ory. The primary to ol is dock er-compose . The too l is used by the scr ipt bin/do cker_cui_c reate.sh | |
| 7 | ||
| 8 | THe `bin/d ocker_cui_ create.sh --help` co mmand shou ld provide sufficien t instruct ion on how to build docker con tainers. | |
| 9 | ||
| 10 | The purpos e of this document i s to assis t develope rs in gett ing a dock er-based d eveloper t est enviro nment runn ing on the ir worksta tions. | |
| 11 | ||
| 12 | ## Contain ers / Serv ices | |
| 13 | ||
| 14 | The DEAP/C UI/CPP app lication u ses three docker con tainers: d b, redis a nd web. T hese conta iners are built usin g the name _docker-co mpose.yml and name_s ervice.yml (where na me is db, redis or w eb) files found in t he directo ry config/ docker. | |
| 15 | ||
| 16 | The name_d ocker-comp ose.yml fi les are mo stly simil ar to each other. T hey each m ake use of the `m4` macro `sin clude()` t o include the name_s ervice.yml file. Th e `m4` com mand line utility is a common *nix utili ty that pr ovides mac ro text pr ocessing s ervices. In this ap plication it is used to do fil e import/i ncludes th at are not inherentl y supporte d by the d ocker tech nology. | |
| 17 | ||
| 18 | To build t he three i mages/cont ainers use the follo wing comma nd from th e Rails.ro ot directo ry: | |
| 19 | ||
| 20 | bin/do cker_cui_c reate.sh d b redis we b | |
| 21 | ||
| 22 | To build t he images/ containers in a way where they can be te sted on a local deve lopment wo rkstation do this: | |
| 23 | ||
| 24 | bin/do cker_cui_c reate.sh l ocalhost | |
| 25 | ||
| 26 | ||
| 27 | ||
| 28 | ### db Ser vice | |
| 29 | ||
| 30 | The db ser vice is im plemented within a c ontainer/i mage with the name d b_server. The db_se rver encap sulates an implement ation inst ance of th e PostgreS QL version 9.3 relat ional data base manag ement syst em. The b ase platfo rm image i s obtained from the official i mage maint ained by t he Postgre SQL team o n the dock er hub web site. | |
| 31 | ||
| 32 | ### redis Service | |
| 33 | ||
| 34 | The redis service is implement ed within a containe r/image wi th the nam e redis_se rver. The redis_ser ver encaps ulates an implementa tion insta nce of the redis-ser ver versio n 3.2.8. The base p latform im age is obt ained from the offic ial image maintained by the Re dis team o n the dock er hub web site. | |
| 35 | ||
| 36 | ### web Se rvice | |
| 37 | ||
| 38 | The web se rvice is i mplemented within a container/ image with the name web_server . The web _server en capsulates an implem entation i nstance of this appl ication. The base p latform im age is obt ained from the offic ial image maintained by the Ru by team on the docke r hub webs ite. This base imag e is versi on 2.3.3 o f RUby. T he web_ser ver image is built u p in layer s using th e config/d ocker/web_ dockerfile configura tion file. On top o f the base platform layer is t he Ruby ge ms layer. This laye r consists of all of the RUby gems (aka libraries) used by t he DEAP/CU I/CPP appl ication. The final layer of t he web_ser ver image is the act ual Rails applicatio n. | |
| 39 | ||
| 40 | Using laye rs allows for faster rebuilds of the web _server im age. For changes th at only im pact the R ails appli cation, on ly the top layer of the images is rebuil d. When a dding or d eleting ge ms, the ge m library layer and the applic ation laye r are rebu ilt. | |
| 41 | ||
| 42 | ||
| 43 | ### localh ost is a s pecial ser vice confi guration | |
| 44 | ||
| 45 | Looking at the confi g/docker/l ocalhost_d ocker-comp ose.yml fi le you wil l notice t hat it use s the `m4` macro `si nclude()` to import all three services - db, redis and web. Also note that it e xpands on the web se rvice by u sing the ` links:` co nfiguratio n element. The `lin ks:` block indicates to the do cker syste m that the re are add itional se rvices whi ch are to be 'linked ' (e.g. ma de availav le) to the current s ervice. T he web ser vice makes use of th e both the db and re dis servic es. | |
| 46 | ||
| 47 | The docker technolog y stack wi ll configu re a speci al DNS (do main namin g service) which rel ates the n ame of a l inked serv ice to a h ostname of the ident ical value . This me ans that w ithin the web servic e context/ image/cont ainer in t he localho st configu ration tha t the DBHO ST system environmen t variable needs to be set to 'db'; like wise, the REDIS_HOST environme nt variabl e needs to be set to 'redis'. | |
| 48 | ||
| 49 | ## First T ime | |
| 50 | ||
| 51 | The first time that you create the local host confi guration o f service containers on your d evelopment workstati on you wil l need to set some a dditional system env ironment v ariables i n you `.en v.local` f ile. The first time the web_s erver is e xecuted it will need to config ure the da tabase. I t does thi s via a ra ke task `p rep:db` wh ich is def ined in th e file lib /tasks/pre p.rake. | |
| 52 | ||
| 53 | The guts o f the `pre p:db` task is this: | |
| 54 | ||
| 55 | if DBR ESET && Rails.env. developmen t? | |
| 56 | Rake ::Task["db :reset"].i nvoke | |
| 57 | elsif DBMIGRATE | |
| 58 | Rake ::Task["db :migrate"] .invoke | |
| 59 | if D BSEED | |
| 60 | Ra ke::Task[" db:seed"]. invoke | |
| 61 | end | |
| 62 | elsif DBSEED | |
| 63 | Rake ::Task["db :seed"].in voke | |
| 64 | end | |
| 65 | ||
| 66 | There are three kern el-level c onstants u sed: DBRES ET, DBMIGR ATE and DB SEED. The se kernel constants are set in `config/i nitializer s/aarp.rb` using the `truth_or _consequen ces()` met hod found in the fil e `lib/tru th_or_cons equences.r b` which t akes a sys tem enviro nment vari able and t urns it in to a boole an constan t based up on its str ing value. | |
| 67 | ||
| 68 | If the sys tem enviro nment vari able DBRES ET is set to some "t ruthy" val ue (eg. 't rue', 'yes ', 'yep', 'y', 'sure ' ) then i ts corresp onding con stant will have a tr ue value. Any other string va lue for th e variable will resu lt in a fa lse value for its co nstant. | |
| 69 | ||
| 70 | The bottom line is t hat the en vironment variable D BRESET mus t be set t o "true" f or the fir st time th e docker c ontainers are used o n your wor kstation i n the loca lhost conf iguration. This wil l build th e database structure and conte nt using t he rake ta sk `db:res et` prior to startin g the web applicatio n. | |
| 71 | ||
| 72 | After that first tim e the DBRE SET variab le should be set to false to a void rebui lding the database. On those times in w hich you c ontaineriz ed databas e needs to be rebuil d you can either use the DBRES ET=true me thod to re build ever ything or just use D BMIGRATE=t rue or DBS EED=true f or a quick er rebuild of the da tabase. | |
| 73 | ||
| 74 | ||
| 75 | ### Access ing the Ap plication | |
| 76 | ||
| 77 | The docker services expose por ts to the host machi ne in a wa y that doe s not requ ire you to know thei r IP addre ss. | |
| 78 | ||
| 79 | The two sy stem envir onment var iables tha t control the web_se rver's por ts are: PUMA_PORT and DOCKER _HOST_WEB_ PORT. The defaul t from the file `.en v` for PUM A_PORT is PORT . The defaul t for DOCK ER_HOST_WE B_PORT is the same. This means that you can use th e browser on your de velopment workstatio n to acces s the Rail s applicat ion runnin g in the w eb_server container with this URL: | |
| 80 | ||
| 81 | [http://lo calhost: PORT ](http://l ocalhost: PORT ) | |
| 82 | ||
| 83 | ||
| 84 | ### Confli cts with l ocalhost p orts | |
| 85 | ||
| 86 | If you hav e running natively o n your wor kstation a db, redis or web se rver that is using t he same po rts as the DEAP/CUI/ CPP applic ation, you can avoid conflicts between y ou worksta tion nativ e applicat ions and t hose same applicatio ns that ar e running within the container s by chang ing the va lues of th e associat ed environ ment varia bles. For exampl e, if you are runnin g PostgreS QL nativel y on your workstatio n on its n ormal defa ult port o f PORT and you w ant to run the db_se rver conta iner just change the value of DBPORT in your '.env .local' fi le from PORT to PORT (or whate ver port y ou want) a nd like ma gic there is not con flict. The same i s true for the REDIS _PORT and DOCKER_HOS T_WEB_PORT . | |
| 87 | ||
| 88 | ||
| 89 | ### Startu p Problems | |
| 90 | ||
| 91 | After doin g `bin/doc ker_cui_cr eate.sh lo calhost` y ou will no tice what looks like an error condition when the s cript term inates. T he is a fa lse error. We don't know why its showin g up. It can be ign ored. To see what t he status is of the system you can alway s review t he logs us ing this c ommand: | |
| 92 | ||
| 93 | docker logs web_ server | |
| 94 | ||
| 95 | The first time you b uild the c ontainer w ith the DB RESET=true value, th e `bin/doc ker_cui_cr eate.sh` s cript to c omplete be fore the c ontainer h as finishe d its work of starti ng un the applicatio n server. Viewing t he logs wi ll show yo u that the container is still in the pro cess of do ing its `r ake db:res et` task. Be patien t - take a coffee br eak. The process of configuri ng the dat abase cont ainer from the web c ontainer o n a develo per's work station wi ll take on the order of 15 min utes on a MacOSX pla tform. | |
| 96 | ||
| 97 | Here us wg at a build ing sessio n looks li ke ... | |
| 98 | ||
| 99 | ruby-2 .3.3@deap Git:PP-552 cpp_featu re $ bin/d ocker_cui_ create.sh localhost | |
| 100 | awk:/u sr/local/b in/awk | |
| 101 | m4:/us r/bin/m4 | |
| 102 | Establ ishing env ironment . .. | |
| 103 | Sour cing .env ... | |
| 104 | Sour cing .env. developmen t ... | |
| 105 | Sour cing .env. local ... | |
| 106 | Sour cing .env. developmen t.local .. . | |
| 107 | ||
| 108 | Buildi ng and lau nching the applicati on contain ers from l ocalhost_d ocker-comp ose.yml .. . | |
| 109 | Comman d: docker- compose -f localhost _docker-co mpose.yml -p CPP up -d --build | |
| 110 | Pullin g redis (r edis:3.2.8 )... | |
| 111 | Pullin g db (post gres:9.3). .. | |
| 112 | Buildi ng web | |
| 113 | Creati ng redis_s erver | |
| 114 | Creati ng db_serv er | |
| 115 | Creati ng web_ser ver | |
| 116 | bin/do cker_cui_c reate.sh: line 104: 3.2.8:: co mmand not found | |
| 117 | ruby-2 .3.3@deap Git:PP-552 cpp_featu re $ | |
| 118 | ||
| 119 | Note how t he last li nes ends w ith "comma nd not fou nd" ... It does not indicate a nything wr ong with t he docker container creation a nd launch process. Using the `docker lo gs` comman d on any o f the cont ains will show a nor mal startu p. | |
| 120 | ||
| 121 | ||
| 122 | ## bin/doc kerinfo | |
| 123 | ||
| 124 | This utili ty will di splay some vital inf ormation a bout all o f the dock er contain ers on you r workstat ion. It a lso displa ys a small knowledge base of do cker comma nds that a re usefull on a deve loper's wo rkstation. | |
| 125 | ||
| 126 | Here is an example o utput when all three container s are runn ing. | |
| 127 | ||
| 128 | ruby-2 .3.3@deap Git:PP-552 cpp_featu re $ bin/d ockerinfo | |
| 129 | ||
| 130 | ┌─ ───⠔€â”€â”€â” €â”€â”€â”€ ───⠔¬â”€â”€â” €â”€â”€â”€ ───⠔€â”€â”€â” €â”€â”€â”€ ┬──⠔€â”€â”€â” €â”€â”€â”€ ┬──⠔€â”€â”€â” €â”€â”€â”€ ───⠔€â”€â”€â” €â”€â”€â”€ ┬──⠔€â”€â”€â” €â”€â”€â”€ ───⠔ | |
| 131 | │ Co ntainer ID │ Conta iner Name │ Status │ Cont ainer IP:P ort │ Ho st IP â ”‚ | |
| 132 | ├─ ───⠔€â”€â”€â” €â”€â”€â”€ ───⠔¼â”€â”€â” €â”€â”€â”€ ───⠔€â”€â”€â” €â”€â”€â”€ ┼──⠔€â”€â”€â” €â”€â”€â”€ ┼──⠔€â”€â”€â” €â”€â”€â”€ ───⠔€â”€â”€â” €â”€â”€â”€ ┼──⠔€â”€â”€â” €â”€â”€â”€ ───⠔¤ | |
| 133 | │ e3 1e8d6caaf4 │ web_s erver │ runnin g │ 172. 23.0.4:456 7 │ 17 2.23.0.1 â ”‚ | |
| 134 | │ 83 f78a331dcc │ db_se rver │ runnin g │ 172. 23.0.3:154 32 │ 17 2.23.0.1 â ”‚ | |
| 135 | │ bb f17c93299f │ redis _server │ runnin g │ 172. 23.0.2:637 9 │ 17 2.23.0.1 â ”‚ | |
| 136 | └─ ───⠔€â”€â”€â” €â”€â”€â”€ ───⠔´â”€â”€â” €â”€â”€â”€ ───⠔€â”€â”€â” €â”€â”€â”€ ┴──⠔€â”€â”€â” €â”€â”€â”€ ┴──⠔€â”€â”€â” €â”€â”€â”€ ───⠔€â”€â”€â” €â”€â”€â”€ ┴──⠔€â”€â”€â” €â”€â”€â”€ ───⠔˜ | |
| 137 | ||
| 138 | Tge rest i f the outp ut is a su mmary of u seful dock er command s. Those command wi th more de tailed des cription i s shown in the next section of this docu ment. | |
| 139 | ||
| 140 | ## Useful Docker Com mands | |
| 141 | ||
| 142 | ### docker logs (con tainer nam e) | |
| 143 | Shows the log file o f a contai ner which is a littl e confusin g semantic ally becau se what is really be ing shown is the STD OUT and ST DERR outpu t. Any co ntainer ap plication which writ es its log informati on to a fi le will ha ve its log informati on in that designate d file and not STDOU T or STDER R. The wa y to see t hose kinds of log fi les is to run a BASH shell on running co ntainer, ` cd` into t he proper log direct ory and `c at` or `le ss` the ch osen log f ile. | |
| 144 | ||
| 145 | ### docker exec -it (container name) bas h | |
| 146 | Opens a ba sh shell o n a runnin g containe r. This i s a prefer red way of accessing the runni ng contain er. The t ypical doc ker docume ntation te ll you to do a `dock er attach` which onl y connects your host 's termina l window t o the STDO UR, STDERR and STDIN streams o f the cont ainer. Mo st (if not all) cont ainerized applicatio ns are run ning in th e foregrou nd. Attac hing to th e standard I/O strea m does not give you the abilit y to poke around and make chan ges to the environme nt as nece ssary. | |
| 147 | ||
| 148 | ### docker (start|st op) (conta iner name) | |
| 149 | Starts or stops a co ntainer. You can th ink of a c ontainer a s a virtua l machine which can be paused and restar ted from t he point a t which it was pause d. That i s what the stop and start dock er command s allow yo u to do. | |
| 150 | ||
| 151 | ### docker images | |
| 152 | Shows all docker ima ges on you r workstat ion. Thes e are imag es from wh ich contai ners are b uilt. Som e images h ave descri ptive name s. Others may only h ave an ima ge ID hex string. T he images with only the image ID are mos t likely l ayers that are built on top of other ima ges to for m a contai ner. | |
| 153 | ||
| 154 | ### docker inspect ( container name) | |
| 155 | Show detai ls about a container 's configu ration. T he result is a JSON string. D epending o n how your terminal/ console wi ndow is co nfigured t his JSON s tring will be easy t o read. | |
| 156 | ||
| 157 | ### docker ps | |
| 158 | Shows all currently running co ntainers. Simple to a standar d *NIX `ps ` command. | |
| 159 | ||
| 160 | ### bin/de lete_docke r_images_e tal.rb --h elp | |
| 161 | Utility to delete do cker image s and cont ainers. I f you ente r no param eters you will get t he same ki nd of outp ut generat ed by the `docker im ages` comm and. Usin g the `--h elp` param eter will provide a list of ot her comman d line opt ions. The two curre ntly suppo rted are: | |
| 162 | ||
| 163 | --dele te-contain ers | |
| 164 | --dele te-images | |
| 165 | ||
| 166 | They can b e used tog ether or s eparately. This uti lity progr am is used to return your work station to a blank s late by de leting all the local docker co ntainers a nd images known to y our host c omputer. You can de lete the c ontainers and rebuil d them fro m the exis ting local images. This avoid s the need to downlo ad the req uired imag es from th e [docker hub websit e](https:/ /hub.docke r.com/). | |
| 167 | ||
| 168 | ||
| 169 | ### bin/do cker_cui_c reate.sh d b redis we b | |
| 170 | Builds and starts th is project 's contain ers. The configurat ion for th e differen t containe rs and ima ges used b y this app lication a re located in the `c onfig/dock er` direct ory. Thes e config f iles are p rocessed b y the `doc ker_cui_cr eate.sh` s cript thro ugh a stan dard *NIX `m4` text preprocess or. The r esulting c onfigurati on files a re tempora rily store d in the R ails.root directory. The `.gi tignore` f ile has be en modifie d to ignor e docker c onfigurati on files i n the root directory . | |
| 171 | ||
| 172 | The reason the confi guration f iles are p re-process ed and mov ed into th e root dir ectory of the projec ts is beca use the do cker techn ology stac k as of it s current version ha s signific ant known errors w/r /t to its use of fil esystem pa ths. The most stabl e way to h andle file system pat hs is to p ut the con figuration files in the root d irectory. This howe ver is poo r project organizati on. | |
| 173 | ||
| 174 | Also the c urrent ver sion of th e docker t echnology stack no l onger supp orts the ` extends` c apability found in o lder versi ons. The extends ca pability a llowed for a docker container to make us e of a set of base s ervices an d extend t he configu ration for different deploymen t environm ents. Thi s amounted to a way in which i ndividual services c ould be co nfiguratio n managed outside of their dep loyed conf iguration. The func tional was lost when the docke r system w as redesig ned/reprog rammed fro m the `pyt hon` langu age into t he `go` la nguage. | |
| 175 | ||
| 176 | ||
| 177 |
Araxis Merge (but not the data content of this report) is Copyright © 1993-2016 Araxis Ltd (www.araxis.com). All rights reserved.