docs/octopus_docs/opnfv-artifact-repository.rst

   1 ===========================
   2  OPNFV Artifact Repository
   3 ===========================
   4
   5 Artifact Repository
   6 ===================
   7
   8 What is Artifact Repository
   9 ---------------------------
  10
  11 An Artifact Repository is akin to what Subversion is to source code, i.e.
  12 it is a way of versioning artifacts produced by build systems, CI, and so on. [1]
  13
  14 Why Artifact Repository is Needed
  15 ---------------------------------
  16
  17 Since many developers check their source code into the GIT repository it may seem natural
  18 to just place the files you've built into the repo too.
  19 This can work okay for a single developer working on a project over the weekends
  20 but with a team working on many components that need to be tested and integrated, this won't scale.
  21
  22 The way git works, no revision of any file is ever lost.
  23 So if you ever check in a big file, the repository will always contain it,
  24 and a git clone will be that much slower for every clone from that point onward.
  25
  26 The golden rule of revision control systems applies:
  27 *check in your build scripts, not your build products*.
  28
  29 Unfortunately, it only takes one person to start doing this and we end up with huge repositories.
  30 Please don't do this. It will make your computers sad.
  31 Thankfully, Gerrit and code review systems are a massive disincentive to doing this.
  32
  33 You definitely need to avoid storing binary images in git. This is what artifact repositories are for. [2]
  34
  35 A “centralized image repository” is needed that can store multiple versions of various virtual machines
  36 and have something like /latest pointing to the newest uploaded image.
  37 It could be a simple nginx server that stores the output images from any jenkins job if it's successful, for instance.
  38
  39 OPNFV Artifact Repository
  40 =========================
  41
  42 What is used as Artifact Repository for OPNFV
  43 ---------------------------------------------
  44
  45 Setting up, hosting, and operating an artifact repository on OPNFV Infrastructure
  46 in Linux Foundation (LF) environment requires too much storage space.
  47 It is also not a straightforward undertaking to have robust Artifact Repository and provide 24/7 support.
  48
  49 OPNFV Project decided to use **Google Cloud Storage** as OPNFV Artifact Repository due to reasons summarized above. [3]
  50
  51 Usage of Artifact Repository in OPNFV CI
  52 ----------------------------------------
  53
  54 Binaries/packages that are produced by OPNFV Continuous Integration (CI) are deployed/uploaded
  55 to Artifact Repository making it possible to reuse artifacts during later stages of OPNFV CI.
  56 Stored artifacts can be consumed by individual developers/organizations as well.
  57
  58 In OPNFV, we generally produce PDF, ISO and store them on OPNFV Artifact Repository.
  59
  60 OPNFV Artifact Repository Web Interface
  61 ----------------------------------------
  62
  63 OPNFV Artifact Repository is accessible via link http://artifacts.opnfv.org/.
  64
  65 A proxy has been set up by LF for the community members located in countries with access restrictions to Google http://build.opnfv.org/artifacts/.
  66
  67 Access Rights to OPNFV Artifact Repository
  68 ==========================================
  69
  70 As summarized in previous sections, OPNFV uses Google Cloud Storage as Artifact Repository.
  71 By default, everyone has read access to it and artifacts can be fetched/downloaded using browser,
  72 a curl-like command line HTTP client, or gsutil.
  73
  74 Write access to Artifact Repository is given per request basis and all the requests
  75 must go through `LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_ with an explanation
  76 regarding the purpose of write access.
  77 Once you are given write access, you can read corresponding section to store artifacts on OPNFV Artifact Repository.
  78
  79 How to Use OPNFV Artifact Repository
  80 ====================================
  81
  82 There are 3 basic scenarios to use OPNFV Artifact repository.
  83
  84 * browsing artifacts
  85 * downloading artifacts
  86 * uploading artifacts
  87
  88 Please see corresponding sections regarding how to do these.
  89
  90 How to Browse Artifacts Stored on OPNFV Artifact Repository
  91 -----------------------------------------------------------
  92
  93 You can browse stored artifacts using
  94
  95 * **Web Browser**: By navigating to the address `OPNFV Artifact Storage <http://artifacts.opnfv.org/>`_.
  96
  97 * **Command Line HTTP-client**
  98     ``curl -o <output_filename> http://artifacts.opnfv.org``
  99
 100     Example:
 101
 102     ``curl -o opnfv-artifact-repo.html http://artifacts.opnfv.org``
 103
 104 * **Google Storage Util (gsutil)**
 105     ``gsutil ls gs://artifacts.opnfv.org/<path_to_bucket>``
 106
 107     Example:
 108
 109     ``gsutil ls gs://artifacts.opnfv.org/octopus``
 110
 111 How to Download Artifacts from OPNFV Artifact Repository
 112 --------------------------------------------------------
 113
 114 You can download stored artifacts using
 115
 116 * **Web Browser**: By navigating to the address `OPNFV Artifact Storage <http://artifacts.opnfv.org/>`_ and clicking the link of the artifact you want to download.
 117
 118 * **Command Line HTTP-client**
 119     ``curl -o <output_filename> http://artifacts.opnfv.org/<path/to/artifact>``
 120
 121     Example:
 122
 123     ``curl -o main.pdf http://artifacts.opnfv.org/octopus/docs/release/main.pdf``
 124
 125 * **Google Storage Util (gsutil)**
 126     ``gsutil cp gs://artifacts.opnfv.org/<path/to/artifact> <output_filename>``
 127
 128     Example:
 129
 130     ``gsutil cp gs://artifacts.opnfv.org/octopus/docs/release/main.pdf main.pdf``
 131
 132 How to Upload Artifacts to OPNFV Artifact Repository
 133 ----------------------------------------------------
 134
 135 As explained in previous sections, you need to get write access for OPNFV Artifact Repository
 136 in order to upload artifacts.
 137
 138 Apart from write access, you also need to have Google account and have the
 139 Google Cloud Storage utility, **gsutil**, installed on your computer.
 140
 141 Install and Configure gsutil
 142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 143
 144 Please follow steps listed below.
 145
 146 1. Install gsutil
 147
 148    ``sudo pip install gsutil``
 149
 150    in case of troubles:
 151
 152    ``sudo pip uninstall gsutil``
 153    ``sudo pip install gsutil``
 154
 155 2. Configure gsutil
 156
 157     Issue below command and follow the instructions. You will be asked for the project-id.
 158 The project-id is **linux-foundation-collab**.
 159
 160     ``gsutil config``
 161
 162 3. Request write access for OPNFV Artifact Repository
 163
 164     Send an email to `LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_ and list the reasons for the request. Do not forget to include gmail mail address.
 165
 166     Or:
 167
 168     Contact aricg on irc in #opnfv-octopus and pass him the accounts.google.com/o/oauth2/auth line, and he will send you the auth response in a private message.
 169
 170 Upload Artifacts
 171 ~~~~~~~~~~~~~~~~
 172
 173 Once you installed and configured gsutil and got write access from LF Helpdesk,
 174 you should be able to upload artifacts to OPNFV Artifact Repository.
 175
 176 The command to upload artifacts is
 177
 178     ``gsutil cp <file_to_upload> gs://artifacts.opnfv.org/<path/to/bucket>``
 179
 180     Example:
 181
 182     ``gsutil cp README gs://artifacts.opnfv.org/octopus``
 183
 184 Once the upload operation is completed,
 185 you can do the listing and check to see if the artifact is where it is expected to be.
 186
 187     ``gsutil ls gs://artifacts.opnfv.org/<path/to/bucket>``
 188
 189     Example:
 190
 191     ``gsutil ls gs://artifacts.opnfv.org/octopus``
 192
 193 Getting Help
 194 ============
 195
 196 Send an email to `LF Helpdesk <opnfv-helpdesk@rt.linuxfoundation.org>`_ or join the channel **#opnfv-octopus** on IRC.
 197
 198 References
 199 ----------
 200 1. `Why you should be using an Artifact Repository <http://blogs.collab.net/subversion/why-you-should-be-using-an-artifact-repository-part-1>`_
 201 2. `Regarding VM image and Git repo <http://lists.opnfv.org/pipermail/opnfv-tech-discuss/2015-January/000591.html>`_
 202 3. `Google Cloud Storage <https://cloud.google.com/storage/>`_