Gemnasium Enterprise Documentation

Contents:

Welcome

Welcome to the Gemnasium Enterprise 1.5 documentation, where you can find information and guides to help you with Gemnasium Enterprise and start exploring its features.

Use the left navigation bar to browse the documentation, the Search bar in the top-left to look for something specific, or the links below to access some highlights.

Note

Gemnasium Enterprise Edition will be referred as “GEE” in this documentation

Release Notes

1.5.0 - 2017-12-15

  • [FEATURE] Add support for gems.rb et gems.locked files
  • [FEATURE] Improve parsing of Maven version numbers
  • [FEATURE] Add support of Gemnasium maven plugin
  • [FEATURE] Allow user to regenerate API Key
  • [FEATURE] Improve project vulnerabilities page with filters and search
  • [FEATURE] Add Admin area with users list
  • [FEATURE] Allow an Admin to block/unblock a user
  • [FEATURE] Add a welcome page to create first Admin (only for new install)
  • [FEATURE] Add support for reCAPTCHA on plain signup
  • [FEATURE] Update sidebar design with big icons
  • [BUG] Invalid headers were causing “Connection lost” issues on some browsers (especially Safari)
  • [MISC] Removed Quay support

1.4.3 - 2017-11-28

  • [BUG] Fix Bitbucket Server oauth sign-in when hosted in a subdirectory (e.g.: https://example.com/bitbucket)
  • [BUG] Fix the commit date displayed on the project page.
  • [FEATURE] Plain sign-up (with user/password) can now be disabled with the env var DISABLE_PLAIN_AUTH set to “true”

1.4.2 - 2017-11-15

1.4.1 - 2017-11-13

  • [BUG] Fix a regression affecting Bitbucket Server integration

1.4.0 - 2017-10-26

  • [FEATURE] Java (Maven support)

1.3.1 - 2017-06-20

  • [SECURITY] CSP headers have been refined
  • [BUG] Fix a bug randomly preventing some users to auth with user / password (when OAuth login sources are present)
  • [BUG] Fix a bug in Slack hook creation (returned URL was escaped twice)
  • [BUG] Fix sidebar when browsing GEE anonymously
  • [BUG] Fix broken page when coming back from Slack OAuth with error
  • [BUG] Fix projects not being removed from dashboard after deletion
  • [BUG] Repos metadata were not synchronized before the project was actually synced
  • [BUG] Other minor fixes

1.3.0 - 2017-05-19

  • [FEATURE] Allow to search and filter projects and project dependencies.
  • [BUG] Fix project settings for synced projects

1.2.2 - 2017-05-03

  • [FEATURE] Project repositories are now synced daily. In case a webhook is not working, the project will be up-to-date at least once per day
  • [FEATURE] Project logs improved, displaying the user (with their IP) who triggered the entry
  • [FEATURE] Add link to team invitation, in case the email is not received by the invitee (particularly usefull if SMTP is not configured)
  • [BUG] Some logs were not flushed to disk on exit (when restarting Gemnasium Enteprise)

1.2.1 - 2017-04-19

  • [FEATURE] Add Let’s Encrypt Certificates support
  • [FEATURE] Support Python “compatible release” operator (~=) as specified in PEP 440
  • [BUG] Invitations to team were sent again if role was updated

1.2.0 - 2017-04-10

  • [FEATURE] Add package pages
  • [FEATURE] Add Packages changelogs
  • [FEATURE] Project page revamped
  • [FEATURE] Add Yarn support
  • [DOC] Fix documentation for integrations
  • [BUG] Fix a bug with PHP dependencies using the caret operator
  • [BUG] The button “Refresh repositories” was emptying the list with bitbucket.org

1.1.3 - 2017-03-21

  • Gemnasium Enterprise is now also available on Quay.io

1.1.2 - 2017-02-16

  • [BUG] Minor bug and fixes
  • [BUG] UI pages now expose an error to the user if the backend is not available.
  • [FEATURE] New button to copy the notification channels of a project to all the projects of the team
  • [FEATURE] New MAILER_EMAIL_FROM env var to specify the sender of GEE email notifications
  • [DOC] Added documentation for CA certs used in integrations
  • [DOC] Added documentation for users behind proxies

1.1.1 - 2017-02-03

  • [BUG] Fix webhook handler. The service in charge of receiving and triggering a project sync was returning a 200 and dropping the event in some cases.

1.1.0 - 2017-01-31

  • [FEATURE] Add Bitbucket Server support
  • [BUG] Weekly digests are now sent on Monday mornings, 8am, instead of Sunday at midnight
  • [BUG] Adding an empty project from GitHub/Gitlab/bitbucket.org was causing the webhook registration to fail. The project bootstrapping was considered as finished, and the project was not synced after the first commit.

Note: We have switched to Webpack 2 for assets bundling, this is transparent for users.

1.0.0 - 2017-01-27

Same as 1.0.0-rc1.

1.0.0-rc1 - 2017-01-16

This is the last pre-release before 1.0.0, if no bug is found.

  • [FEATURE] Add Bitbucket.org (Bitbucket Cloud) Support
  • [FEATURE] Add project logs with realtime update
  • [FEATURE] Improve project notification channels configuration
  • [FEATURE] Allow to edit existing project notification channel
  • [FEATURE] Improve user notifications configuration
  • [BUG] Fix various UI bugs
  • [BUG] Some PHP packages were not fully synced

1.0.0-beta4 - 2016-12-15

  • [FEATURE] “New package release” notifications via Slack and email
  • [BUG] Fix file upload form when adding unsupported file
  • [BUG] Fix left menu bar behavior on small devices layout
  • [BUG] Fix oauth signup error handling

1.0.0-beta3 - 2016-11-29

  • [FEATURE] GitLab Support
  • [FEATURE] New notifications in the UI

Known issues:

  • [BUG][GITLAB] Symlinks on dependency files are not followed
  • [BUG][GITLAB] Dependency files greater than 2MB are ignored
  • [BUG] Can’t sign-in using an oauth account if the same email is already used

1.0.0-beta2 - 2016-11-18

  • [FEATURE] Display commits in project page
  • [FEATURE] Internal logging (live feeds will be available in beta3)
  • [BUG] Fix a security issue when adding a project to a team. The tokens of the team owner were used instead of the user’s.
  • [BUG] Fix display issues in Firefox
  • [BUG] Fix UI Cache issues
  • [BUG] Offline projects color was not updated when pushing new dependency files
  • [BUG] Sync was failing when commit already existed
  • [BUG] Fix a bug preventing to upload new files in Offline projects

Known issues:

  • [FEATURE] Gitlab support is delayed to beta3
  • [BUG] Can’t sign-in using an oauth account if the same email is already used

1.0.0-beta1 - 2016-10-21

  • First private beta
  • GitHub.com and GitHub Enterprise support
  • Slack integration for notifications

Gemnasium Enterprise License Agreement

Note

Last update : 2017-10-20

Tech-Angels Inc.’s Gemnasium Enterprise software (“Tech-Angels”, “Gemnasium, “we”, or “us”) helps you deliver better and secured software by providing detailed information regarding your application’s dependencies. Before you download and/or use our enterprise software, we need you to agree to a special set of terms. Welcome to the Software License Agreement (the “Agreement”).

PLEASE READ THIS AGREEMENT CAREFULLY BEFORE INSTALLING OR USING THE SOFTWARE. THESE TERMS AND CONDITIONS GOVERN YOUR USE OF THE SOFTWARE (AS DEFINED BELOW), UNLESS WE HAVE EXECUTED A SEPARATE WRITTEN AGREEMENT WITH YOU FOR THAT PURPOSE. WE’RE ONLY WILLING TO LICENSE THE SOFTWARE TO YOU IF YOU ACCEPT ALL THE TERMS AND CONDITIONS OF THIS AGREEMENT. BY INSTALLING OR USING THE SOFTWARE OR BY CLICKING “I ACCEPT” ON OUR SITE, YOU ARE CONFIRMING THAT YOU UNDERSTAND THIS AGREEMENT, AND THAT YOU ACCEPT ALL OF ITS TERMS AND CONDITIONS. IF YOU ARE ENTERING INTO THIS AGREEMENT ON BEHALF OF A COMPANY OR OTHER LEGAL ENTITY, YOU REPRESENT THAT YOU HAVE THE LEGAL AUTHORITY TO BIND THE ENTITY TO THIS AGREEMENT, IN WHICH CASE “YOU” WILL MEAN THE ENTITY YOU REPRESENT. IF YOU DON’T HAVE SUCH AUTHORITY, OR IF YOU DON’T ACCEPT ALL THE TERMS AND CONDITIONS OF THIS AGREEMENT, THEN WE ARE UNWILLING TO LICENSE THE SOFTWARE TO YOU, AND YOU MAY NOT DOWNLOAD, INSTALL, OR USE IT.

1. DEFINITIONS

Here are some definitions we use in this Agreement. If you see a capitalized word that isn’t listed here, it will be defined somewhere in the Agreement.

Agreement Effective Date
is the earlier of the date that you either click “I Accept” to the terms and conditions of this Agreement, or that you first place an order for Software or Services.
Documentation
means any manuals, documentation and other supporting materials related to the Software that we generally provide to our customers. Documentation is considered part of the Software.
Fees
means both: (i) the fees you’re required to pay us to use the Software during the applicable License Term, as such fees are reflected on each applicable Order Form; and (ii) the fees you’re required to pay us for any Services you engage us to perform, as such fees are reflected on each applicable SOW (“ Statement of Work ”).
License Key
means a data file or character string utilized by the Software’s access control mechanism that allows you to use the Software during the License Term.
License Term
means one (1) year from the applicable Order Effective Date.
Order Form
is a written or electronic form that we’ll give you to order Software (or that we’ll use to order Software on your behalf, once we’ve gotten your authorization). Upon execution by the parties (or, in the case of an electronic orders, confirmation and placement of the order), each Order Form will be subject to the terms and conditions of this Agreement.
Order Effective Date
is the effective date of each Order Form.
Projects
mean the number of projects (public or private) to monitor you’re authorized to add to the software. The number of Projects is specified in the applicable Order Form.
Services (aka “Professional Services”)
means training, consulting, or implementation services that we provide to you pursuant to a mutually executed Statement of Work. Services do not include support.
Software
means the object-code/obfuscated source code version of our proprietary enterprise software application. Software includes any applicable Documentation, as well as any Updates to the Software that we provide you or that you can access under this Agreement.
Statement of Work (or “SOW”)
means a mutually executed statement of work detailing the Services we’ll perform for you, their price, and your related obligations (if any).
Update
is a Software release that we make generally available to our customers, along with any corresponding changes to Documentation. An Update may be an error correction or bug fix, generally indicated by a change in the digit to the right of the second decimal point (e.g., a change from version x.x.x to x.x.y); or it may be an enhancement, new feature, or new functionality, generally indicated by a change in the digit to the right of the first decimal point (e.g., x.x.x to x.y.x) or to the left of the first decimal point (e.g., x.x.x to y.x.x).
User
is a single person or machine account that initiates the execution of the Software and/or interacts with or directs the Software in the performance of its functions. Your license does not limit the number of Users.
Team
is a logical group of Users.
Gemnasium Data
refers to all data fetched by the Software on Gemnasium servers to synchronize packages data, including (but not limited to) advisories, changelogs and licences.

2. LICENSE GRANT

Subject to your compliance with the terms of this Agreement (including, among other things, paying the Fees you owe us), we hereby grant you a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to install, execute, and use a single production instance of the Software for your internal business purposes during the applicable License Term, in accordance with the Documentation, and only for the number of Projects that you’ve paid for. You can make copies of the Software for non-production purposes only, provided that you reproduce all copyright and other proprietary notices that are on the original copy of the Software. Your agents and contractors can use the Software too, so long as they’re using it on your behalf, and provided that you agree to be fully responsible for their behavior under this Agreement.

3. RESTRICTIONS

We license the Software to you – we don’t sell it. As between us, we own all right, title and interest in and to the Software, and any intellectual property rights associated with it and with our company. We reserve all rights in and to the Software that we don’t expressly grant you in this Agreement. You agree not to, nor permit nor authorize any third party to: (i) sublicense, sell, rent, lease, transfer, assign, or distribute the Software or Gemnasium Data to third parties; (ii) host the Software or Gemnasium Data for the benefit of third parties; (iii) disclose or permit any third party to access the Software or Gemnasium Data, except as expressly permitted in Section 2, above; (iv) hack or modify the License Key, or try to avoid or change any license registration process we may implement; (v) modify or create derivative works of the Software, or merge the Software with other software, or merge Gemnasium Data with other database; (vi) disassemble, decompile, bypass any code obfuscation, or otherwise reverse engineer the Software or attempt to derive any of its source code, in whole or in part, except to the extent such activities are expressly permitted by law or applicable license notwithstanding this prohibition; (vii) modify, obscure, or delete any proprietary rights notices included in or on the Software or Documentation; (viii) otherwise use or copy the Software in a manner not expressly permitted by this Agreement; or (ix) use any Software that we license to you beyond its applicable License Term.

4. PROJECTS

Projects can be added (only) in a Team namespace in Gemnasium Enterprise. You can add as many teams as you want. There are no restriction on the number of users per team. A User can be part of several Teams. If you want to swap out, delete, or archive a Project, you can do that, and then add a new Project to a Team. If you find that you need more Projects slots, that’s great – we’re here to help! Just submit a new request through our website or via our sales team, and pay for the additional Projects (a new Order Form will be generated). If and when you add additional Projects to your subscription, you’ll pay Fees for those Projects at the then-current price, prorated for the balance of the applicable License Term. When the time comes to renew your License, we’ll invoice you for all of your Projects at once, at the then-current price (we reserve the right to change our prices at any time, but the new prices won’t affect you until it’s time to renew your license). You agree that any orders that you make (or that you authorize us to make on your behalf) for additional Projects during the term of this Agreement will be governed by this Agreement.

5. VERIFICATION

From time to time, we may have reason to make sure that you’re not using extra Projects without paying for them. You agree to cooperate with us to achieve that goal. To help us verify the number of Projects you’re actually using, you agree to promptly give us any usage files and reports that your instance of the Software generates, if and when we ask for them. We might also (or instead) ask one of your officers to certify the number of Projects that you’re actually using. You agree to provide such a certification if we ask for it. If we determine that you’re using more Projects than you’ve paid for, in addition to any other remedies we might have at law or in equity, you agree to pay us the then-current Fees for the additional Projects you’re using, starting from the date you began using each Project.

5. GOVERNMENT USERS

No technical data or computer software is developed under this Agreement. The Software and Documentation have been developed solely with private funds, and are considered “Commercial Computer Software” and “Commercial Computer Software Documentation” as described in FAR 12.212, FAR 27.405-3, and DFARS 227.7202-3, and are licensed to the to the U.S. Government end user as restricted computer software and limited rights data. Any use, disclosure, modification, distribution, or reproduction of the Software or Documentation by the U.S. Government or its contractors is subject to the restrictions set forth in this Agreement.

7. DELIVERY

Promptly after the applicable Order Effective Date, we’ll make the Software and the License Key available for you to download on a secure, password-protected website. As Updates become available, we’ll make those available for you to download on the same website. You’re responsible for maintaining the confidentiality of all of your usernames and passwords, including the ones you use to download the Software. Take good care of them, because you agree that you’ll be responsible for any activity that takes place using your usernames and passwords (whether you knew about it or not).

8. SERVICES

Our Services can help you get the most out of the Software. If you want Services, let us know, and we’ll work with you to prepare a SOW that describes the date, time, location, and objectives of the Services, as well as the price. Each SOW will be binding once we both sign it, and you agree that any Services we provide to you (whether pursuant to a SOW or not) will be governed exclusively by the terms of this Agreement. In the event of any conflict between the terms of this Agreement and any SOW, the terms of this Agreement will control. Provided you comply with the terms of this Agreement (including, among other things, paying us the Fees you owe us), we’ll perform the Services described in each SOW, according to the timeframes set forth in that SOW. We’ll control the manner and means by which the Services are performed, and we reserve the right to determine which personnel we assign to perform Services for you. Provided we remain responsible for all of their acts and omissions, we can use third parties to help us perform the Services. You acknowledge that we will retain all right, title and interest in and to anything we use or develop in connection with performing Services for you, including, among other things, software programs, tools, specifications, ideas, concepts, inventions, processes, techniques, and know-how. To the extent we deliver anything to you during the course of performing Services, we grant you a non-exclusive, non-transferable, worldwide, royalty-free, limited-term license to use those deliverables during the term of this Agreement, solely in conjunction with your use of the Software.

9. TERM AND TERMINATION

9.1 Term. This Agreement starts on the Agreement Effective Date and will continue in effect for either one (1) year or on a month-to-month basis (the “Initial Term”), at which time, so long as you choose to renew your Software license for additional License Terms (which, to be clear, you’re under no obligation to do), this Agreement will automatically continue in effect for additional one (1) year or monthly terms (each, a “Renewal Term”) until this Agreement is either terminated by a party or expires in accordance with this Section 8.

9.2 Termination for Convenience; Automatic Expiration. Either of us can terminate this Agreement for our convenience at the end of the Initial Term or any Renewal Term by providing written notice to the other at least thirty (30) days before the end of the Initial Term or any Renewal Term. This Agreement will automatically expire without the requirement of notice if, at the end of the Initial Term or any Renewal Term, you decide not to pay the Fees required to renew your Projects slots for an additional License Term.

9.3 Termination for Breach. We can terminate this Agreement immediately upon notice to you if you breach any part of it, and you fail to cure the breach within thirty (30) days of us notifying you of it. That said, there are certain kinds of breaches that we take much more seriously, and that can really damage us. We therefore reserve the right to terminate this Agreement immediately upon written notice to you, but without giving you a cure period, if you breach any of the terms of this Agreement relating to our intellectual property (including your compliance with the license grant and any license restrictions) or our Confidential Information (defined below).

9.4 Effect of Termination. When this Agreement terminates or expires: (i) the License Term for any Software in your possession will immediately end, and any outstanding SOWs will immediately terminate; (ii) you’ll no longer have the right to use the Software, and any licenses we grant you in this Agreement will automatically cease to exist as of the date of termination/expiration; (iii) if you owed us any money prior to termination/expiration, you’ll need to pay us all that money immediately; (iv) you’ll destroy all copies of the Software in your possession or control, and certify in writing to us that you’ve done so; and (v) each of us will promptly return to the other (or, if the other party requests it, destroy) all Confidential Information belonging to the other. You’ll still be able to access the Software to migrate your data for ninety (90) days after termination or expiration of this Agreement, but you won’t be allowed to use the Software on a production basis during that time. Sections 1, 3, 5, 6, 8, 9.2, 9.3, 9.4, 11, 12.2, and 13-17 will survive the termination or expiration of this Agreement for any reason.

10. SUPPORT

10.1 Support Times. Provided that you’ve paid us the Fees you owe us, we’ll provide you with technical support for the Software twelve (12) hours per day, five (5) days per week, excluding weekends and national U.S. Holidays. We currently only offer support via email (write to us at support@gemnasium.com) or web-based ticketing (through http://support.gemnasium.com or the directly Help widget if available by your network policy). You can contact our amazing support team to help answer your questions on installing and using the Software, identifying and verifying the causes of suspected errors in the Software, and helping you find workarounds for Software malfunctions. Though we’ll do our best to respond to automated support requests, we typically need more information than an automated ticketing system can give us to solve your issue. Whenever possible, please initiate any support requests from a person or machine that our support team can interact with. We like the personal touch.

10.2 Updates. We’ll make Updates available to you on the same secure website where you downloaded the Software. You may also want to subscribe to our Gemnasium Enterprise newsletter to get notified of news and updates.

10.3 Exclusions. We might not be able to correct every problem we find, but we’ll use our reasonable efforts to correct any material, reproducible errors in the Software that you make us aware of. We might ask for your help in reproducing the error for us. Please - don’t do things with our Software that would make it harder for us to help you. We won’t be responsible for supporting you in those circumstances, which include, among other things: (i) someone (other than us) modifying the Software; (ii) changing your operating system or environment in a way that adversely affects the Software or its performance; (iii) using the Software in a manner for which it was not designed, or other than as authorized under this Agreement; or (iv) accident, negligence, or misuse of the Software. We’re only required to support a given version of the Software for a year from the date of its commercial release, or six months from the commercial release of the next Update, whichever is longer. If you want support for earlier versions of the Software, we’ll try to help you if we can, but you’ll need to pay us for that help at our then-current rates.

11. PAYMENT

You agree to pay the Fees to us in full, without deduction or setoff of any kind, in U.S. Dollars (unless the Order Form says otherwise), within 30 days of the date of the invoice we send you related to the applicable SOW or Order Form. Amounts payable under this Agreement are nonrefundable, except as provided in Section 12.1. If you don’t pay us on time, we reserve the right, in addition to taking any other action that we see fit, to charge you interest on past due amounts at 1.0% per month or the highest interest rate allowed by law, whichever is less, and to additionally charge all expenses of recovery. You are solely responsible for all taxes, fees, duties and governmental assessments (except for taxes based on Tech-Angels’ net income) that are imposed or become due in connection with the subject matter of this Agreement.

12. LIMITED WARRANTIES

12.1 Limited Warranties. We offer you (and only you) the following limited warranties: (i) that the unmodified Software, at the time we make it available to you for download, will not contain or transmit any malware, viruses, or worms (otherwise known as computer code or other technology specifically designed to disrupt, disable, or harm your software, hardware, computer system, or network); (ii) that any Services we perform for you under this Agreement will be performed in a good and workmanlike manner, by appropriately qualified personnel (you just need to let us know about a problem within thirty (30) days of the date the Services were performed); and (iii) that, for ninety (90) days from the date the Software is made available for download, the unmodified Software will substantially conform to its Documentation. We don’t warrant that your use of the Software will be uninterrupted, or that the operation of the Software will be error-free. These warranties won’t apply if you modify the Software, or if you use the Software in any way that isn’t expressly permitted by this Agreement and the Documentation. Our only obligation, and your only remedy, for any breach of these limited warranties will be, at our option and expense, to either (i) repair the Software; (ii) replace the Software; or (iii) terminate this Agreement with respect to the defective Software, and refund the Fees you’ve paid for the defective Software during the then-current License Term once you’ve returned it to us (or destroyed it).

12.2 Disclaimer. THE LIMITED WARRANTIES DESCRIBED ABOVE ARE THE ONLY WARRANTIES WE MAKE WITH RESPECT TO THE SOFTWARE, SERVICES AND OUR TECHNICAL SUPPORT. WE DON’T MAKE ANY OTHER WARRANTIES, AND WE HEREBY SPECIFICALLY DISCLAIM ANY OTHER WARRANTIES, WHETHER EXPRESS, IMPLIED, OR STATUTORY, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, OR ANY WARRANTIES OR CONDITIONS ARISING OUT OF COURSE OF DEALING OR USAGE OF TRADE. NO ADVICE OR INFORMATION, WHETHER ORAL OR WRITTEN, THAT YOU GET FROM US OR ANYWHERE ELSE WILL CREATE ANY WARRANTY OR CONDITION NOT EXPRESSLY STATED IN THIS AGREEMENT.

13. LIMITATION OF LIABILITY

13.1 Waiver of Consequential Damages. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT WILL WE BE LIABLE TO YOU OR TO ANY THIRD PARTY FOR ANY INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, OR CONSEQUENTIAL DAMAGES (INCLUDING FOR LOSS OF PROFITS, REVENUE, OR DATA) OR FOR THE COST OF OBTAINING SUBSTITUTE PRODUCTS ARISING OUT OF OR IN CONNECTION WITH THIS AGREEMENT, HOWEVER CAUSED, WHETHER SUCH LIABILITY ARISES FROM ANY CLAIM BASED UPON CONTRACT, WARRANTY, TORT (INCLUDING NEGLIGENCE), STRICT LIABILITY OR OTHERWISE, AND WHETHER OR NOT WE’VE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

13.2 Limitation of Total Liability. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, OUR TOTAL CUMULATIVE LIABILITY TO YOU OR ANY THIRD PARTY UNDER THIS AGREEMENT, FROM ALL CAUSES OF ACTION AND ALL THEORIES OF LIABILITY, WILL BE LIMITED TO AND WILL NOT EXCEED THE FEES YOU’VE ACTUALLY PAID US DURING THE 12 MONTHS PRECEDING THE CLAIM GIVING RISE TO SUCH LIABILITY.

13.3 Basis of Bargain. You understand and agree that we’ve set our prices and entered into this Agreement with you in reliance upon the limitations of liability set forth in this Agreement, which allocate risk between us and form the basis of a bargain between the parties.

14. INDEMNIFICATION

14.1 Our Indemnification Obligation. We’ll defend or settle, at our option and expense, any third-party claim brought against you to the extent that it’s based on an allegation that your use or possession of the Software as permitted under this Agreement infringes a copyright or misappropriates a trade secret of any third party (each, a “Claim”), and, subject to Section 13, we’ll pay all damages and costs (including reasonable legal fees) finally awarded by a court of final appeal attributable to such a Claim, provided that you notify us in writing of any such Claim as soon as reasonably practicable and allow us to control, and reasonably cooperate with us in the defense of, any such Claim and related settlement negotiations.

14.2 Exclusions. You understand that we’ll have no obligation to indemnify you for any Claim that’s based on (i) the modification of the Software, unless we were the ones who made the modifications; (ii) your use of the Software other than as authorized by this Agreement and the Documentation; (iii) your failure to use updated or modified Software that we make available to you that would have helped avoid or mitigate the Claim; (iv) your failure to stop using the Software after receiving written notice to do so from us in order to avoid further infringement or misappropriation; or (v) the combination, operation or use of the Software with equipment, devices, software, systems, or data that we didn’t supply (subparts (i)-(v) may be referred to collectively as “Indemnity Exclusions”).

14.3 Right to Ameliorate Damages. If your use of the Software is, or in our reasonable opinion is likely to be, subject to a Claim under Section 14.1, we may, at our sole option and at no charge to you (and in addition to our indemnity obligation to you in Section 14.1): (i) procure for you the right to continue using the Software; (ii) replace or modify the Software so that it is non-infringing and substantially equivalent in function to the original Software; or (iii) if options (i) and (ii) above are not commercially practicable in our reasonable estimation, we can terminate this Agreement and all licenses granted hereunder (in which event, you will immediately stop using the Software) and refund the Fees that you paid us for the then-current License Term.

14.4 Sole Remedy. THIS SECTION 14 SETS FORTH OUR SOLE AND EXCLUSIVE OBLIGATIONS, AND YOUR SOLE AND EXCLUSIVE REMEDIES, WITH RESPECT TO CLAIMS OF INFRINGEMENT OR MISAPPROPRIATION OF THIRD PARTY INTELLECTUAL PROPERTY RIGHTS.

14.5 Your Indemnification Obligation. Because we can’t know what you’re doing with the Software behind your firewall, except to the extent that we’re obliged to indemnify you in Section 14.1 above, you will defend, indemnify, and hold us harmless from and against any claims that may arise out of or that are based upon (i) your breach of this Agreement; (ii) content that you upload to the Software; or (iii) an Indemnity Exclusion.

15. CONFIDENTIALITY

15.1 Definition of Confidential Information. For the purposes of this Agreement, “Confidential Information” means any business or technical information that either one of us discloses to the other, in writing, orally, or by any other means, and including things like computer programs, code, algorithms, data, know-how, formulas, processes, ideas, inventions (whether patentable or not), schematics and other technical, business, financial, and product development plans, names and expertise of employees and consultants, and customer lists. For the purposes of this Agreement, except as expressly set forth in Section 17.2 below, the source code of our Software will be deemed to be Tech-Angels’ Confidential Information, regardless of whether it is marked as such.

15.2 Restrictions on Use and Disclosure. Neither of us will use the other party’s Confidential Information, except as permitted under this Agreement. Each of us agrees to maintain in confidence and protect the other party’s Confidential Information using at least the same degree of care as we use for its own information of a similar nature, but in all events at least a reasonable degree of care. Each of us agrees to take all reasonable precautions to prevent any unauthorized disclosure of the other’s Confidential Information, including, without limitation, disclosing Confidential Information only to its employees, independent contractors, consultants, and legal and financial advisors (collectively, “Representatives”) (i) with a need to know such information, (ii) who are parties to appropriate agreements sufficient to comply with this Section 15, and (iii) who are informed of the nondisclosure obligations imposed by this Section 15. Each of us will be responsible for all acts and omissions of our Representatives. The foregoing obligations won’t restrict either of us from disclosing Confidential Information of the other party pursuant to the order or requirement of a court, administrative agency, or other governmental body, provided that the party required to make such a disclosure gives reasonable notice to the other party to enable them to contest such order or requirement. The restrictions set forth in this Section 15 will survive the termination or expiration of this Agreement.

15.3 Exclusions. The restrictions set forth in Section 15.2 will not apply with respect to any Confidential Information that: (i) was or becomes publicly known through no fault of the receiving party; (ii) was rightfully known or becomes rightfully known to the receiving party without confidential or proprietary restriction from a source other than the disclosing party who has a right to disclose it; (iii) is approved by the disclosing party for disclosure without restriction in a written document which is signed by a duly authorized officer of such disclosing party; or (iv) the receiving party independently develops without access to or use of the other party’s Confidential Information.

16. GOVERNING LAW AND JURISDICTION

This Agreement will be governed by and interpreted in accordance with the laws of the State of Florida, without giving effect to any principles of conflict of laws. The parties expressly agree that the United Nations Convention on Contracts for the International Sale of Goods and the Uniform Computer Information Transactions Act will not apply to this Agreement. Any legal action or proceeding arising under, related to or connected with this Agreement will be brought exclusively in the federal (if they have jurisdiction) or state courts located in the Broward County, FL and the parties irrevocably consent to the personal jurisdiction and venue there.

17. MISCELLANEOUS

17.1 Assignment. You aren’t allowed to assign or transfer any of your rights or obligations in this Agreement, in whole or in part, by operation of law or otherwise, without our prior written consent, and any attempt by you to do so without our consent will be null and void. We can assign this Agreement in its entirety, upon notice to you but without the requirement to obtain consent, in connection with a merger, acquisition, corporate reorganization, or sale of all or substantially all of our business or assets.

17.2 Availability of Source Code. The Software source code may be provided upon request if Tech-Angels determines that it is necessary to do so.

17.3 Severability. In the event that any provision of this Agreement is deemed by a court of competent jurisdiction to be illegal, invalid, or unenforceable, the court will modify or reform this Agreement to give as much effect as possible to that provision. Any provision that can’t be modified or reformed in this way will be deemed deleted, and the remaining provisions of this Agreement will continue in full force and effect.

17.4 Notices. Any notice, request, demand or other communication required or permitted under this Agreement should be in writing (e-mail counts), should reference this Agreement, and will be deemed to be properly given: (i) upon receipt, if delivered personally; (ii) upon confirmation of receipt by the intended recipient, if by e-mail; (iii) five (5) business days after it is sent by registered or certified mail, with written confirmation of receipt; or (iv) three (3) business days after deposit with an internationally recognized express courier, with written confirmation of receipt. Notices should be sent to the address(es) set forth on the Invoice, unless we notify each other that those addresses have changed.

17.5 Waiver. A party’s obligations under this Agreement can only be waived in a writing signed by an authorized representative of the other party, which waiver will be effective only with respect to the specific obligation described. Any waiver or failure to enforce any provision of this Agreement on one occasion will not be deemed a waiver of any other provision or of such provision on any other occasion.

17.6 Force Majeure. We will be excused from performing under this Agreement to the extent that we’re unable to perform due extraordinary causes beyond our reasonable control. That might include things like acts of God, strikes, lockouts, riots, acts of war, epidemics, communication line failure, and power failures.

17.7 Independent Contractors. We’re each independent contractors with respect to the subject matter of this Agreement. Nothing contained in this Agreement will be deemed or construed in any manner whatsoever to create a partnership, joint venture, employment, agency, fiduciary, or other similar relationship between us, and neither of us can bind the other contractually.

17.8 Amendments; Entire Agreement. No modification, change, or amendment of this Agreement will be binding upon the parties, unless we both agree to the change in a writing signed by each of our authorized representatives. This Agreement, including each Order Form and SOW, constitutes the entire agreement and understanding of the parties with respect to its subject matter, and supersedes any and all prior or contemporaneous understandings and agreements, whether oral or written, between the parties with respect to its subject matter.

Note

Software licenses used to develop Gemnasium Enterprise are available in /usr/local/share/gemnasium/licenses

Getting Started

What is Gemnasium Enterprise?

Gemnasium Enterprise Edition (GEE) is the self-hosted version of Gemnasium, designed to run on your own servers, inside your network. A private license key is required to use the software, otherwise no data will be synced with gemnasium.com (making your instance unusable).

To get a valid license key, please contact our support.

First steps

Gemnasium Enterprise is designed as a collaborative tool. Each project must be added inside a team context, that’s why the first thing to do is to create your team. The name must be unique in the Gemnasium Enterprise instance.

Add your collegues

Go to the “Team” section of the main menu, and press the “+ Add member” button to invite co-workers. The role of the invited user will grant him/her access to your team:

  • “Admin” users will be able to manage project and users
  • “Basic” users will be able to access projects only

Add projects

The first shortcut in the main menu “+ Add project” will allow you to add new projects to a team. Once the team is selected, a source must be chosen. By default, only “offline” projects are available, because your instance doesn’t know anything about external sources.

Offline projects will allow to upload dependencies files (Gemfile, Gemfile.lock, package.json,...) directly to a project. This kind of project is called “offline”, because Gemnasium can’t synchronize the files with an external source.

To add projects from github.com, or GitHub Enterprise, an external source must be created. Please refer to the corresponding pages in the “INSTALLATION AND CONFIGURATION” section of this documentation. More source types will be available in the next versions of Gemnasium Enterprise.

Prerequisites

Subscriptions

  • As Gemnasium Enterprise is provided as a docker image, you must have a Docker Hub account to download it.
  • A Gemnasium Enterprise license is required. If do not have your license yet, please contact our support.

System Requirements

Hardware

  • Physical or virtual system, or an instance running on a public or private IaaS.
  • 1 vCPU
  • Minimum of 2GB RAM
  • Minimum 20GB hard disk space

Software

  • OS: RedHat (RHEL, Atomic Host, Centos & Fedora flavors), Debian Stable. Any OS running docker should work but is not officially supported.
  • Docker >= 1.9.1

License key

As you will see, in all the docker run commands, there is a -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \. You need to replace YOUR_OWN_LICENSE_KEY with the license we gave you. If you don’t have one, please get in touch and we’ll get that sorted.

Firewall configuration

Gemnasium Enterprise is designed to run behind your firewalls, inside your network. It should be completely isolated from the outside, especially from incoming connections.

Incoming traffic

Gemnasium only exposes two ports:

Port Usage Protocol
80 clear connection http
443 secure connection https

It’s your responsibility to configure your network and firewall to restrict access to these ports. By default, Gemnasium exposes port 80 only to redirect to port 443. Custom ports might be used, refer to Configuring SSL if needed.

Outgoing traffic

While Gemnasium Enterprise should be completely isolated from the outside for incoming connections, some outgoing traffic is necessary for normal operation. The following ports must be open on your firewall for outgoing traffic:

Address Port Protocol Usage
sync.gemnasium.com 443 tcp Sync with Gemnasium main DB
index.docker.io 443 tcp Pull updates of gemnasium/enterprise image, if used.

What data is sent to sync.gemnasium.com?

Your content is private, and will remain private. But synchronizing all packages, versions, changelogs, advisories, etc. with Gemnasium’s main DB would require a huge amount of storage and a lot of bandwidth.

To avoid this situation, your instance of Gemnasium Enterprise periodically sends a list of the packages (dependencies) used in your projects to https://sync.gemnasium.com In return, Gemnasium syncer provides all the metadata corresponding to this request, including the security advisories. Gemnasium keeps the following information in private log entries:

  • Timestamp of the current sync request
  • Customer (based on license key)
  • Gemnasium version used
  • Number of packages per type (gems, npms, ...)

Note

Private dependencies are completely ignored by the syncer.

Advisories can be created at any time on Gemnasium.com; that’s why your instance synchronizes hourly. If one of your projects is using a dependency affected by a security issue, you will be notified by your instance within the hour.

Note

Gemnasium is using data (advisories) from security companies (partnerships only). Your data will never be submitted directly to these companies, but Gemnasium may share anonymized statistical data.

Run Gemnasium Enterprise

Gemnasium Enterprise is shipped as a single, all-included docker image.

Download Gemnasium Enterprise

In order to be able to download the Gemnasium Enterprise docker image, you must have an account on Docker Hub.

Send us the name of the account used and we will share the image with that user.

QuickStart: Docker Compose

The easiest and fastest way to start with Gemnasium Enterprise is to use Docker Compose. Docker Compose is a command line tool available for free (and most of the time bundled with your Docker installation). With a single file, the minimum configuration needed by Gemnasium Enterprise is available at a glance. It’s a good start, and the configuration should be tuned up with the rest of this page sections for production.

Use this docker-compose.yml file to get started:

version: "3"
services:
  gemnasium:
    container_name: gemnasium
    build: .
    image: gemnasium/enterprise
    restart: unless-stopped
    ports:
      - "80:80"   # api unsecure
      - "443:443"  # api ssl
    environment:
      - EXTERNAL_URL=https://gemnasium.localhost
      - SMTP_SERVICE_HOST
      - SMTP_SERVICE_PORT
      - SMTP_USER_NAME
      - SMTP_PASSWORD
      - SMTP_INSECURE
      - LICENSE_KEY
    volumes:
        - gemnasium-data:/var/opt/gemnasium/
volumes:
    gemnasium-data:
        driver: local

Note

The env vars must be declared in docker-compose.yml otherwise they are ignored (see Environment Variables.).

Preparing volumes

Persistent volumes are needed to store Gemnasium Enterprise data. The easiest way to get started, is to create local volumes on your server, but it can be any kind of volume supported by the docker engine.

See also

Please refer to Docker Volumes for more information: https://docs.docker.com/engine/tutorials/dockervolumes/

To create local volumes, on you server:

docker volume create --name gemnasium-data
docker volume create --name gemnasium-logs

Configuring SSL

A valid certificate must be provided to run Gemnasium Enterprise with the integrated SSL web server. If you don’t have a valid certificate available, you can obtain one from Let’s Encrypt for free. Please refer to the Let’s Encrypt Certificates section. If you don’t need Gemnasium Enterprise to serve content on https directly, go directly to the section: Running without SSL.

The certificate files must be named after the server name.

Example: for gemnasium.example.com, the certificate files must be named:

  • gemnasium.example.com.cert.pem for the certificate
  • gemnasium.example.com.key.pem for its private key

Gemnasium will look for 2 files with the .cert.pem and .key.pem suffix.

If the certificate has an intermediate chain, it must concatenated after the server certificate:

cat server.cert.pem ca-chain.cert.pem > gemnasium.example.com.cert.pem

The 2 files must be available in /etc/gemnasium/ssl, inside the container.

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 443:443 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gemnasium/enterprise:latest

Note

Gemnasium needs the docker socket to be mounted only if the Reports feature is being used. If not, the line -v /var/run/docker.sock:/var/run/docker.sock can be safely removed.

This will pull and start Gemnasium Enterprise. Your instance will be available at https://gemnasium.example.com after a few seconds.

If you need to use a different port for https than 443, use the EXTERNAL_URL env var to specify the full URL of your Gemnasium Enterprise server, including the port used:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 8443:443 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -e EXTERNAL_URL=https://gemnasium.example.com:8443/ \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gemnasium/enterprise:latest

and start browsing https://gemnasium.example.com:8443/

Running without SSL

Warning

We strongly discourage running Gemnasium Enterprise without any SSL termination. This section is present if you already have SSL terminations, like secured reverse-proxies, ssl appliances, etc.

Run the image:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -e REDIRECT_HTTP_TO_HTTPS=false \
  -e EXTERNAL_URL=http://gemnasium.example.com/ \
  -p 80:80 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  gemnasium/enterprise:latest

Note

The environment variable REDIRECT_HTTP_TO_HTTPS is true by default, and must be false in this case.

The service is available after a few seconds on the port 80 of your server. Use the EXTERNAL_URL variable to specify the full URL of your Gemnasium Enterprise server, including the port if necessary.

SELinux

Gemnasium Enterprise can’t be run directly on SELinux servers, because:

  1. The volumes will be readonly by default
  2. The docker socket will be restricted to the host

Use this command instead:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 443:443 \
  -e LICENSE_KEY=YOUR_OWN_LICENSE_KEY \
  -v gemnasium-data:/var/opt/gemnasium/:Z \
  -v gemnasium-logs:/var/log/:Z \
  -v /var/run/docker.sock:/var/run/docker.sock:Z \
  gemnasium/enterprise:latest

This will label the content inside the container with the exact MCS label that the container will run with, basically it runs chcon -Rt svirt_sandbox_file_t -l s0:c1,c2 /var/db where s0:c1,c2 differs for each container.

Please refer to this project to install the proper SELinux module to fix the second point.

Volumes

Gemnasium is storing data in two folders, which should be mounted as volumes

Local location Location in container Usage
gemnasium-data (volume) /var/opt/gemnasium Gemnasium data
gemnasium-logs (volume) /var/log Gemnasium logs

Gemnasium data is composed mostly of the PostgreSQL database files, but also nsq data, etc. These files must be backed up, refer to the Data Backup. section.

The /var/log contains the OS logs, and everything dedicated to gemnasium in /var/log/gemnasium.

Finally, as explained in the Configuring SSL section, your certificate and key must be available in the /etc/gemnasium/ssl folder.

Logging

By default, all logs will be sent to the standard output of the container (stdout), along with files in /var/log. This makes it easier to troubleshoot if needed.

Graylog

Gemnasium Enterprise can be configured to log to a distant Graylog server. To enable this feature, use the following environment variables:

Env variables Usage
GRAYLOG_SERVICE_HOST Graylog input hostname/ip
GRAYLOG_SERVICE_PORT Graylog input port

Example:

docker run --detach  \
  --name gemnasium \
  --restart always \
  -v /host/path/to/ssl/:/etc/gemnasium/ssl \
  -p 80:80 -p 443:443 \
  -v gemnasium-data:/var/opt/gemnasium/ \
  -v gemnasium-logs:/var/log/ \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e GRAYLOG_SERVICE_HOST=logs.example.log
  -e GRAYLOG_SERVICE_PORT=1515
  gemnasium/enterprise:latest

Both variables must be set to activate the GELF output.

Obtaining a shell

The docker image doesn’t have a SSH server, because docker provides everything needed to get a shell console inside the container:

docker exec -it gemnasium bash

will create a new bash session, with the root user.

Warning

With great power comes great responsibility: as root, you can damage files inside the container, including your persisted data.

SMTP setup

In order to send notifications (team invitations, digests, etc.), Gemnasium Enterprise needs a SMTP server. There is no such server included in the docker image, so an external SMTP server should be used. Note that SMTP connectivity is not fully required, just recommended.

Configuration

SMTP can be configured by passing environment variable to the docker container:

Env variables Usage
SMTP_SERVICE_HOST Server host address
SMTP_SERVICE_PORT Server port
SMTP_USER_NAME Username
SMTP_PASSWORD Password
SMTP_INSECURE Skip SSL verification

The SMTP password can be plain auth, or a secret (CRAM-MD5 auth). These variables are all optional.

SSL and TLS are supported, and will be automatically used if the port (SMTP_SERVICE_PORT) is 465 or 587.

The sender for email notifications will be by default app@gemnasium.com which can be an issue with your smtp server. It can be updated by passing the MAILER_EMAIL_FROM environment var to your Gemnasium Enterprise container.

Environment Variables

Gemnasium Enterprise is entirely configured using environment variables.

Variables persistence

If you don’t want to specify by hand all environment variables in docker run, you can create a file including all the variables to be set: Compose expects each line in an env file to be in VAR=VAL format. Lines beginning with # (i.e. comments) are ignored, as are blank lines.

To use the environment file, add the --env-file=[file name] to your docker run command line.

With docker-compose, the name should be named .env in the same directory as your docker-compose.yaml file, and will be loaded automatically. Remember to specify the env variables expected in the file, otherwise docker-compose will simply ignore them.

Variables List

Env variables Usage Required Default
Main
LICENSE_KEY Your GEE private license key required  
EXTERNAL_URL Your GEE full URL required  
ENABLE_LETSENCRYPT_SSL Enable Let’s Encrypt support optional false
Logging
GRAYLOG_SERVICE_HOST Graylog input hostname/ip optional  
GRAYLOG_SERVICE_PORT Graylog input port if GRAYLOG_SERVICE_HOST is set  
SMTP
SMTP_SERVICE_HOST SMTP server host optional  
SMTP_SERVICE_PORT SMTP server port optional 25
SMTP_USER_NAME SMTP user optional  
SMTP_PASSWORD SMTP password (plain auth) or secret (CRAM-MD5 auth) optional  
SMTP_INSECURE SMTP skip SSL verification optional false
MAILER_EMAIL_FROM Email notifications sender optional app@gemnasium.com
Feature toggles
DISABLE_PLAIN_AUTH Allow to disable the plain sign in & sign up feature optional false
Misc
RECAPTCHA_SITE_KEY Your recaptcha site key, for client side integration optional  
RECAPTCHA_SECRET_KEY Your recaptcha secret key, for server side integration optional  

Upgrade Gemnasium Enterprise

While the data about packages, versions, etc. is automatically updated, and stored in your local database, Gemnasium Enterprise won’t upgrade itself automatically.

Using latest version

To upgrade Gemnasium Enterprise to a new version:

1- Pull the new image:

docker pull gemnasium/enterprise:latest

2- Stop and remove the container:

docker rm -f gemnasium

3- Run the image again (see QuickStart: Docker Compose.). Gemnasium Enterprise will update your data automatically, if necessary.

docker run [...]

Note

Please make sure that you don’t accidentally remove the gemnasium container and its volumes using the -v option.

Using nightly version

Every night, a new build of Gemnasium Enterprise will be generated, as a gemnasium/enterprise:nightly image. This image is intended for debugging only, and should not be used for production.

Using a tagged version

The available tags are listed here: https://hub.docker.com/r/gemnasium/enterprise/tags/

It is recommended to always use the latest tag.

Troubleshooting

Read container logs:

docker logs -f gemnasium

Enter running container:

docker exec -it gemnasium /bin/bash

Known issues

Gemnasium Enterprise is using setcap to allow our process running on port 80 and 443 (unless SSL is disabled via REDIRECT_HTTP_TO_HTTPS to false). Some kernels don’t support capacities operations inside containers, especially when AUFS is being used. To avoid an error while running Gemnasium Enterprise, the api server will fallback to use a setuid bit on the server, meaning in the case the service is running as root inside the container. While this is not a security issue for your host, it means the api has full control inside the container, including reading passwords and tokens.

If you are unsure your system is affected by this issue, check the logs of the api service in /var/log/gemnasium/api/current. If setcap is failing, the message Warning: setcap not available, falling back to setuid will be displayed at the top of the log file.

If you want to avoid this issue, you can bind your own ports, higher then 1024, using the env vars GEMNASIUM_API_PORT_8080_TCP_PORT GEMNASIUM_API_SSL_PORT_8443_TCP_PORT. If they are both above 1024, no setcap or setuid method will be used, and the webserver will run as a limited-rights user.

Data Backup

Gemnasium Enterprise will store its data in a persistent volume (cf. Volumes.).

It is YOUR responsibility to backup this volume. Gemnasium Enterprise has no capacities of backing up data.

Snapshots

Disk snapshots are probably the best option to backup your data. All the data stored in the persistent volume will saved at once, and can be restored at anytime.

If a restore is needed, remember to stop the container before restoring anything:

docker stop gemnasium

and remove it completely:

docker rm gemnasium

Once the data is restored, run again the image: QuickStart: Docker Compose

Using docker

As explained in the “Manage data in containers” docker page, docker may be used to create a tarball:

docker run –rm –volumes-from gemnasium -v $(pwd):/backup ubuntu tar cvf /backup/backup.tar /var/opt/gemnasium

It is highly recommanded to stop the container before doing this operation.

Restoring data with docker

With your backup in the local directly (pwd), untar your archive to restore the data in the gemnasium-data volume:

$ docker run --rm -v $(pwd):/backup -v gemnasium-data:/var/opt/gemnasium/ gemnasium/enterprise bash -c "cd /var/opt/gemnasium && tar xvf /backup/backup.tar --strip 1"

Once the data is restored, run again the image: QuickStart: Docker Compose

Proxy configuration

Gemnasium Enterprise is designed to run behind your firewalls, inside your network. If your network is using a proxy to access http or https resources, you may need to adapt GEE configuration.

By default, docker will use a default network bridge, so the network stack is shared with the host where docker is running.

The proxy configuration for Docker is beyond the scope of this documentation, please refer to Docker and your operating system documentation if needed.

Gemnasium Enterprise is using the posix environment vars http_proxy (/HTTP_PROXY) and no_proxy (/NO_PROXY) directly. Set these variables according to your network configuration. All the services inside the container will be aware of these two variables.

NO_PROXY configuration

As Gemnasium Enterprise is composed of several services running inside the container, the communication between the services might be affected by a proxy configuration on your network.

Theses hosts must be added to your current no_proxy var inside the container:

  • Your Gemnasium Enterprise full URL
  • api
  • gemnasium-api
  • gemnasium-auth
  • gemnasium-badges
  • gemnasium-billing
  • gemnasium-notifier
  • gemnasium-repo-syncer
  • nsqlookupd
  • nsqd
  • postgresql

Theses hostnames are added to /etc/hosts when the container is starting, so it’s important that a curl gemnasium-api is working inside the container.

root@60bdf6bb1ab5:/# curl gemnasium-api
<a href="http://docs.gemnasium.apiary.io">Moved Permanently</a>.

Remember that you can also pass an environment file to your docker container with --env-file=[file name], so this file should contain a complete no_proxy definition.

Self-Signed Certificates

Gemnasium Enterprise doesn’t require a certificate signed by a (well-)known authority. As with any other service running on your network, it’s not recommanded to use such certificate, unless a CA certificate is being used to sign it.

Gemnaasium Enterprise will fail to contact your local servers if they are using such certificate, unless the right CA is available in the container.

Note

Only valid (ie: signed by a known authority) certificates will work with Gemnasium Enterprise.

Installing a CA CERT

Gemnasium Enterprise is using a Debian Stable as the operating system. To make sure all services inside the container are using the right certificates, they must be installed into /etc/ssl/certs/. Do not mount a folder on this path directly, as you may hide the current certificates already present (Debian default ones). Each certificate can actually be mounted:

docker run [...] -v [ca-cert file path]:/etc/ssl/certs/[ca-cert file path]:ro gemnasium/enterprise

Note

If you have more than one CA certificate, replicate this parameter for each.

Getting a valid certificate

If you don’t have a valid authority to sign your certificates, you may want to use Let’s Encrypt. They are delivering free certificates.

Let’s Encrypt Certificates

Let’s Encrypt is a free, automated, and open Certificate Authority (CA). You can obtain a valid certificate for your Gemnasium Enterprise instance. There are two different ways to configure your instance to use Let’s Encrypt: Using the integrated client, or using a custom process.

See also

Let’s Encrypt documentation online for detailled information

Integrated Let’s Encrypt client

Gemnasium Enterprise features a Let’s Encrypt client with:

  • Automatic renewal (one week before expiration)
  • TLS-SNI domain validation

The generated certificate will be saved in /etc/gemnasium/ssl along with its private key. If you want to cache/persist these files, mount a volume into your container for this path.

To enable Let’s Encrypt support, use the following variables:

  • ENABLE_LETSENCRYPT_SSL: set to true
  • EXTERNAL_URL: Your Let’s Encrypt hostname (please note that LE only supports port 443)
  • REDIRECT_HTTP_TO_HTTPS: is true by default, leave it as it.

Limitations

By default, the client proves control by answering an HTTPS-based challenge. This requires the host name to resolve to the IP address of a (single) computer running Gemnasium Enterprise. Typically, the challenge won’t work on a shared SSL LoadBalancer with SNI, because let’s encrypt will use server names like *.acme.invalid.

This also means you will probably not be able to get a certificate for your local machine (unless it’s exposed directly to the internet).

Custom process

EFF is providing a full-featured acme client:

https://certbot.eff.org/

Getting the certificate, renew it, etc. must be done outside the Gemnasium container, otherwise your changes will be lost during next Gemnasium update deployment. The generated certificate and key should be installed (ie: mounted into the docker container) directly in /etc/gemnasium/ssl as explained in the Configuring SSL section.

GitHub

GitHub.com

Before being able to add projects from github.com, Gemnasium Enterprise needs to be configured to access it.

This is a two steps process: firs you need to create OAuth applications on GitHub and then configure Gemnasium Enterprise to use them.

1. Adding OAuth applications on GitHub

Gemnasium Enterprise needs two different OAuth applications. One to enable “Login with GitHub” and one to synchronize projects.

To do that:

  • go on https://github.com/settings/developers (or alternatively, add the application to an organization: https://github.com/organizations/[your_org]/settings/applications)
  • click on the “Register a new application” and fill the form:
    • Name: “Gemnasium Enterprise Login”
    • Homepage URL: your Gemnasium Enterprise base URL (example: https://gemnasium.example.com/)
    • Authorization callback URL: {GEMNASIUM_INSTANCE_URL}/auth/auth/github.com/login/callback where you replace {GEMNASIUM_INSTANCE_URL} with the url of your Gemnasium Enterprise instance (example: https://gemnasium.example.com/auth/auth/github.com/login/callback)
  • Click on the “Register application” button.

You will need the “Client ID” and “Client Secret” you see on the confirmation page for the next section. You can keep that tab open and open a new tab to https://github.com/settings/developers to create the second application.

To create the second application required:

  • go on https://github.com/settings/developers
  • click on the “Register a new application” and fill the form:
    • Name: “Gemnasium Enterprise Sync”
    • Homepage URL: your Gemnasium Enterprise base URL (example: https://gemnasium.example.com/)
    • Authorization callback URL: {GEMNASIUM_INSTANCE_URL}/auth/auth/github.com/sync/callback where you replace {GEMNASIUM_INSTANCE_URL} with the url of your Gemnasium Enterprise instance (example: https://gemnasium.example.com/auth/auth/github.com/sync/callback)
  • Click on the “Register application” button.

2. Configure Gemnasium Enterprise to use GitHub

A convenient script is provided to configure your instance:

docker exec -it gemnasium configure

Select “GitHub.com”, and then fill the corresponding fields with the values from the applications created above. Be careful not to confuse Sync and Login applications!

Your Gemnasium Enterprise users are now able to login using their GitHub account. A new source named “GitHub” is also available on the “Add Project” screen.

GitHub Enterprise

GitHub Enterprise is no different than GitHub.com, the steps are the same.

In step 1. Adding OAuth applications on GitHub, just replace github.com with your private GitHub Enterprise instance host (example: https://gemnasium.example.com/auth/auth/private-github.example.com/login/callback).

In step 2. Configure Gemnasium Enterprise to use GitHub, make sure to select “GitHub Enterprise” instead of “GitHub.com”. The script will ask for your GitHub Enterprise instance URL, and to name it.

Several GitHub Enterprise instances can be configured, just name them accordingly to avoid confusion.

Requirements

Gemnasium Enterprise has been tested against GitHub Enterprise >=2.7.X. If your version is older than 2.7 series, please contact our support.

GitLab

GitLab.com

Before being able to add projects from gitlab.com, Gemnasium Enterprise needs to be configured to access it.

This is a two steps process: firs you need to create an OAuth application on GitLab and then configure Gemnasium Enterprise to use that application.

1. Adding the OAuth application on GitLab

  • go on https://gitlab.com/profile/applications
  • fill the form “Add new application”:
    • Name: “Gemnasium Enterprise”
    • Redirect URI: {GEMNASIUM_INSTANCE_URL}/auth/auth/gitlab.com/sync/callback where you replace {GEMNASIUM_INSTANCE_URL} with the url of your Gemnasium Enterprise instance (example: https://gemnasium.example.com/auth/auth/gitlab.com/sync/callback)
    • Scopes: api
  • Click on the “Save application” button.

You will need the “Application Id” and the “Secret” you see on the confirmation page for the next section.

2. Configure Gemnasium Enterprise to use GitLab

A. Automatic configuration

A convenient script is provided to add both Sign In/up and project synchronization with Gitlab at once. If you don’t want both features, check B. Advanced configuration.

docker exec -it gemnasium configure

Select “GitLab.com”, and then fill the corresponding fields with the values from the application created above.

Your Gemnasium Enterprise users are now able to login using their GitLab account. A new source named “GitLab” is also available on the “Add Project” screen.

B. Advanced configuration

The automatic configuration described above enables both Sign In/Up and project synchronization with Gitlab. This advanced configuration makes it possible to restrict the integration to one of these two features.

To enable Gitlab Sign In/Up only, run these commands:

docker exec -it gmenasium auth providers create gitlab.com gitlab 2.0 https://gitlab.com/oauth/authorize https://gitlab.com/oauth/token
docker exec -it gemnasium auth clients create gitlab.com login {OAUTH_APPLICATION_ID} {OAUTH_APPLICATION_SECRET} api

To enable Gitlab Synchronization only, run these commands:

docker exec -it gmenasium auth providers create gitlab.com gitlab 2.0 https://gitlab.com/oauth/authorize https://gitlab.com/oauth/token
docker exec -it gemnasium auth clients create gitlab.com sync {OAUTH_APPLICATION_ID} {OAUTH_APPLICATION_SECRET} api
docker exec -it gemnasium repo-syncer sources create gitlab.com "Gitlab" gitlab https://api.gitlab.com/

{OAUTH_APPLICATION_ID} and {OAUTH_APPLICATION_SECRET} must be replaced with the id and the secret of the OAuth application created on Gitlab. See 1. Adding the OAuth application on GitLab above.

GitLab CE/EE

GitLab CE/EE is no different than GitLab.com, the steps are the same.

In step 1. Adding the OAuth application on GitLab, just replace gitlab.com with your private GitLab CE/EE instance host (example: https://gemnasium.example.com/auth/auth/private-gitlab.example.com/sync/callback).

When using A. Automatic configuration, make sure to select “GitLab CE/EE” instead of “GitLab.com”. The script will ask for your GitLab instance URL, and to name it.

When using B. Advanced configuration, make sure to replace all occurences of gitlab.com with your private GitLab CE/EE instance host. You also need to replace "Gitlab" with the name you want in the last command to enable synchronization feature. This is the name of the source that will show up in the “Add projects” page.

Several GitLab CE/EE instances can be configured, just name them accordingly to avoid confusion.

Requirements

Gemnasium Enteprise is compatible with GitLab >= 8.14. There is a bug in nginx affecting lower versions of GitLab.

Bitbucket Cloud

Before being able to add projects from bitbucket.org (A.K.A. Bitbucket Cloud), Gemnasium Enterprise needs to be configured to be able to access it.

First add an OAuth consumer on bitbucket.org, then configure Gemnasium Enterprise to use that OAuth consumer.

Adding OAuth consumers on Bitbucket.org

The first step is to go to open the “Add OAuth consumer” form:

  • Go to the Bitbucket Settings page.
  • If needed, use the dropdown list and select the Bitbucket account of your company.
  • Click on the “OAuth” item in the sidebar.
  • Click on the “Add consumer” button.

Or simply visit: https://bitbucket.org/account/user/[your_account]/oauth-consumers/new

Then fill the form:

  • Set the name to “Gemnasium Enterprise”.
  • Set the callback URL to be {homepage URL}/auth/auth/bitbucket.org where you replace the home with your Gemnasium Enterprise host (example: https://gemnasium.example.com/auth/auth/bitbucket.org)
  • Set the URL to your Gemnasium Enterprise base URL (example: “https://gemnasium.example.com/”).
  • Grant permissions to: read account, read repositories, read and write webhooks.
  • Save the new OAuth consumer.

You’ll then be redirected to the OAuth Consumers page and the consumer named “Gemnasium Enterprise” will be visible in the list. Click on its name to expand the item and retrieve the credentials: the consumer key and its secret.

Configure Gemnasium Enterprise to use Bitbucket.org

A convenient script is provided to configure your instance:

docker exec -it gemnasium configure

Your Gemnasium Enterprise users are now able to login using their Bitbucket.org account. A new source named “Bitbucket.org” is also available on the “Add Project” screen.

Advanced configuration

The default configuration described above enables both Bitbucket.org Sign In and project synchronization with Bitbucket.org. The advanced configuration makes it possible to restrict the integration to one of these two features.

To enable Bitbucket.org Sign Up, add an OAuth consumer with the permissions “account” and “email”, then run these commands to configure Gemnasium Enterprise accordingly:

docker exec -it gemnasium auth provider create bitbucket.org bitbucket https://bitbucket.org/site/oauth2/authorize https://bitbucket.org/site/oauth2/access_token
docker exec -it gemnasium auth clients create bitbucket.org login OAUTH_CONSUMER_KEY OAUTH_CONSUMER_SECRET account,email

To enable Bitbucket.org Synchronization, add an OAuth consumer with the permissions “repository” and “webhook”, then run these commands to configure Gemnasium Enterprise accordingly:

docker exec -it gemnasium auth provider create bitbucket.org bitbucket https://bitbucket.org/site/oauth2/authorize https://bitbucket.org/site/oauth2/access_token
docker exec -it gemnasium auth clients create bitbucket.org sync OAUTH_CONSUMER_KEY OAUTH_CONSUMER_SECRET repository,webhook
docker exec -it gemnasium repo-syncer sources create bitbucket.org "Bitbucket Cloud" bitbucket https://api.bitbucket.org

OAUTH_CONSUMER_KEY and OAUTH_CONSUMER_SECRET must replaced with the key and the secret of the OAuth consumer created on Bitbucket.org. See Adding OAuth consumers on Bitbucket.org above.

Bitbucket Server

Before being able to add projects from Bitbucket Server (formerly know as Atlassian Stash), Gemnasium Enterprise needs to be configured to be able to access it.

Bitbucket Server is different from the other integrations since OAuth 1.0 is being used, instead of OAuth 2.0.

First add an OAuth consumer on Bitbucket Server, then configure Gemnasium Enterprise to use that OAuth consumer.

Adding OAuth consumers on Bitbucket Server

Before configuring Bitbucket Server, make sure you have the public key of the certificate Gemnasium Enterprise uses to sign off all the requests it sends to OAuth 1.0 providers like Bitbucket Server. This public key is displayed when running the Gemnasium Enterprise configure script (see Configure Gemnasium Enterprise to use Bitbucket Server below).

On Bitbucket Server, OAuth consumers are registered as a special kind of “Application Links” with an “Incoming Authentication” configuration.

To access the “Application Links” settings:

  • Log in Bitbucket Server as an admin,
  • Go to the settings page, or click on the gear icon that’s in the upper-right corner of the page:
_images/settings_gear.png
  • Click on the “Application Links” item that’s under the “SETTINGS” section of the sidebar:
_images/application_link_sidebar.png

Or simply visit https://[bitbucket_server]/plugins/servlet/applinks/listApplicationLinks where bitbucket_server is the hostname of your Bitbucket Server instance.

Then create a new Application Link for Gemnasium Enterprise:

  • Enter the URL of your Gemnasium Enterprise instance,
_images/create_application_links.png

(https://gemnasium.localhost is an example, use your instance URL here)

  • Click on “Create new link”.

Bitbucket Server then shows a warning because it’s not able to probe the URL in order to configure the Application Link automatically. You can safely ignore this warning and proceed by clicking on “Continue”.

_images/warning_no_response.png

Then, fill in the mandatory fields of the “Link application” form:

  • Set the Application Name to “Gemnasium Enterprise”,
  • Set the Application Type to “Generic Application”,
  • Let the other fields empty and click on “Continue”.
_images/application_link_form.png

A new Application Link shows up in the list. Click on pen icon in order to edit its properties.

_images/applications_list.png

Then click on “Incoming Authentication” and fill in the form:

  • Set the Consumer Key to “gemnasium_enterprise”,
  • Set the Consumer Name to “Gemnasium Enterprise”,
  • Paste the Public Key that was given when configuring Gemnasium Enterprise (see Configure Gemnasium Enterprise to use Bitbucket Server below),
  • Set the Consumer Callback URL to {gemnasium_enterprise_url}/auth/auth/{bitbucket_hostname} where you replace gemnasium_enterprise_url with the base URL of your Gemnasium Enterprise and bitbucket_hostname with the hostname of your Bitbucket Server instance (example: https://gemnasium.example.com/auth/auth/bitbucket.example.org)
  • Click on “Save”.
_images/incoming_auth.png

Important

Make sure to use “gemnasium_enterprise” as the Consumer Key

Gemnasium Enterprise can now connect to Bitbucket Server using the OAuth 1.0 protocol.

Configure Gemnasium Enterprise to use Bitbucket Server

A convenient script is provided to configure your instance:

docker exec -it gemnasium configure

When prompted, give the hostname of your Bitbucket Server instance and the OAuth Consumer Key you have registered Gemnasium Enterprise with (example: gemnasium_enterprise).

Your Gemnasium Enterprise users are now able to login using their Bitbucket Server account. Also, a new repository source named “Bitbucket Server” is available on the “Add Project” screen.

Adding project webhooks

Danger

Bitbucket Server API does not provide any way to create webhooks in projects like GitHub or Gitlab (or even bitbucket.org). This operation is therefore manual, and must be executed for each project added to Gemnasium Enterprise.

Go to your Bitbucket Server project setting page, and click on the “Hooks” link.

_images/hooks.png

A webhook plugin must be installed (once) to be able to notify URLs.

  • Click on the “Add Hook” button, then “Search”
_images/add_hook.png
  • A new tab will open with the Atlassian plugins marketplace
  • Search for “Web Post Hooks”, and select the “Bitbucket Server Web Post Hooks Plugin” plugin
_images/hook_plugin.png

Make sure you have the required permission level to install this plugin, or request the installation to an admin of your Bitbucket Server.

  • Once installed, enable the plugin in the project settings:
_images/enable_plugin.png
  • Click on “Post-Receive WebHooks” (or the pen next to the name) to configure the plugin
_images/configure_plugin.png

Enter the following URL:

{gemnasium_enterprise_url}/repo-syncer/repos/{project_slug}/events

where:

  • gemnasium_enterprise_url is the URL of your Gemnasium Enteprise instance, starting with https://
  • project_slug is composed of {bitbucket_hostname}/{project}/{repo}

In our example, the hook URL is https://gemnasium.localhost/repo-syncer/repos/bitbucket.priv.tech-angels.net/GEM/rails-app/events and the repo URL is https://bitbucket.priv.tech-angels.net/projects/GEM/repos/rails-app/browse

Slack

Because it’s an enterprise version installed on your server, you need to do a few things in order to add Slack support.

The first step is to create a new Slack application, on Slack itself. Here are the steps:

  • Go on https://api.slack.com/apps?new_app=1
  • Set the App Name to be “Gemnasium Enterprise”, and then click on the “Create App” button.
  • You will need the Client ID and Client Secret in a moment. You can keep them around or go back to see them when you need them.
  • (optional) By default, there is no Gemnasium icon for the messages sent on Slack. If you want it, which we suggest, you can upload it on the “Basic Information” screen of the app you just created, in the “Display Information” section. You can use this icon..
  • Go in the “OAuth & Permissions” section (in the left menu) and set the redirect URL to https://gemnasium.example.com/auth/auth/slack.com/webhook/callback

Now, we need to configure Gemnasium Enterprise to use it:

docker exec -it gemnasium configure

Select “Slack”, and then fill the corresponding fields with the values from the apps created above.

Now you only need to configure Slack notifications for a project in the web UI. You can do that in the “Settings” of each project.

Ruby

Supported features

  • Gemfile and Gemfile.lock files are supported
  • Gemspec files are supported
  • Security advisories
  • AutoUpdate

Limitations

  • Gemfile with ruby code to be evaluated are not interpreted. Most of the time, this is not an issue, because the Gemfile.lock is a static, generated yaml file.
  • Private repositories and gems are not supported, and won’t be listed in your project.

Javascript

Supported features

  • package.json, npm-shrinkwrap.json and package-lock.json are supported
  • yarn.lock files are supported
  • Security advisories

Limitations

PHP

Supported features

  • composer.json, composer.lock files
  • Packagist packages
  • Security advisories

Limitations

Python

Supported features

  • requirements.txt, requires.txt files are supported
  • Security advisories

Limitations

  • setup.py is only supported on Gemnasium.com
  • All dependencies are considered as “runtime”
  • Pip options (like -r to include another file) are ignored
  • Sections (like [testing]) are ignored

Java

Supported features

  • Maven packages hosted on Maven Central
  • Maven POM XML
  • Security advisories

Limitations

  • Gradle config files are not yet supported
  • Ivy config files
  • What’s not supported in POM XML:
    • Inheritance (coming soon)
    • Aggregation
    • Repositories
    • Plugins

Tools

To draw full benefit from the Maven support we recommend to use the Gemnasium Maven Plugin.

Note

Gemnasium doesn’t process the repositories element since it only knows about the artefacts hosted on Maven Central.