Merge pull request #453 from travis-ci/sw-faq

Merge FAQs and add container-based builds troubleshooting

Author: MariadeAnton

_includes/sidebar.html

@@ -47,25 +47,30 @@ <h2>Menu</h2>
       <ul>
         <li><a href="/user/getting-started/">Getting started</a></li>
         <li><a href="/user/customizing-the-build/">Customizing Your Build</a></li>
+        <li><a href="/user/common-build-problems/">Common Build Problems</a></li>
         <li><a href="/user/installing-dependencies/">Installing Dependencies</a></li>
+        <li><a href="/user/caching/">Caching Dependencies</a></li>
+        <li><a href="/user/private-dependencies/">Private Dependencies</a></li>
         <li><a href="/user/uploading-artifacts/">Uploading Build Artifacts</a></li>
         <li><a href="/user/database-setup/">Setting up Services and Databases</a></li>
         <li><a href="/user/gui-and-headless-browsers/">Headless Testing with Browsers</a></li>
         <li><a href="/user/speeding-up-the-build/">Speeding up the Build</a></li>
         <li><a href="/user/multi-os/">Building on Multiple Operating Systems</a></li>
         <li><a href="/user/docker/">Using Docker in your Build</a></li>
+        <li><a href="/user/pull-requests">Building Pull Requests</a></li>
         <li><a href="/user/language-specific/">Language Guides</a></li>
         <li><a href="/user/deployment/">Deployment Guides</a></li>
         <li><a href="/user/integration/platformio/">Embedded Builds with PlatformIO</a></li>
         <li><a href="/user/encryption-keys/">Encrypting Sensitive Data</a></li>
         <li><a href="/user/encrypting-files/">Encrypting Files</a></li>
         <li><a href="/user/ci-environment/">CI Environment Reference</a></li>
         <li><a href="/user/osx-ci-environment/">OSX CI Environment Reference</a></li>
+        <li><a href="/user/trusty-ci-environment/">Trusty CI Environment</a><li>
         <li><a href="/user/environment-variables/">Environment Variables</a></li>
-        <li><a href="/user/common-build-problems/">Common Build Problems</a></li>
         <li><a href="/user/ssh-known-hosts/">Adding to SSH Known Hosts</a></li>
         <li><a href="/user/github-oauth-scopes/">GitHub Permissions used by Travis CI</a></li>
         <li><a href="/user/migrating-from-legacy/">Migrating to Container-Based Infrastructure</a></li>
+        <li><a href="/user/travis-pro/">Travis CI for Private Projects</a></li>
         <li><a href="/user/build-environment-updates">Build Environment Updates (December 2014 and later)</a></li>
       </ul>
       <h2>Tools</h2>
@@ -94,12 +99,6 @@ <h2>3rd Party Tools and Resources</h2>
         <li><a href="/user/resources/">Links and Resources</a></li>
         <li><a href="https://scan.coverity.com/travis_ci">Coverity Scan</a></li>
       </ul>
-      <h2>Travis Pro</h2>
-      <ul>
-        <li><a href="/user/travis-pro/">Frequently Asked Questions</a></li>
-        <li><a href="/user/private-dependencies/">Private Dependencies</a></li>
-        <li><a href="/user/caching/">Caching Dependencies</a></li>
-      </ul>
     </nav>
   </section>
   <section>

index.html

@@ -36,13 +36,7 @@ <h2>Deployment Guides</h2>
     <section>
       <h2>Common Questions</h2>
       <ul>
-        <li><a href="/user/speeding-up-the-build">How can I make my build faster?</a></li>
-        <li><a href="/user/using-postgresql/#Selecting-a-PostgreSQL-Version">How do I choose a PostgreSQL version?</a></li>
-        <li><a href="/user/using-postgresql/#Using-PostGIS">How do I configure PostGIS for my tests?</a></li>
-        <li><a href="/user/pull-requests">How are pull requests tested?</a></li>
-        <li><a href="/user/build-timeouts">My builds are timing out, what can I do?</a></li>
-        <li><a href="/user/repository-providers">What repository providers can I use?</a></li>
-        <li><a href="/user/pricing/">Why can't I find pricing information?</a></li>
+        <li><a href="/user/customizing-the-build/#What-git-Repository-Providers-can-I-use">What repository providers can I use?</a></li>
         <li><a href="/user/trusty-ci-environment/">Can I use Ubuntu Trusty for my builds?</a><li>
         <li><a href="/user/notifications/#Changing-the-email-address-for-build-notifications">How do I change the notifcation email address?</a><li>
       </ul>

user/build-timeouts.md

@@ -2,6 +2,8 @@
 title: Common Build Problems
 layout: en
 permalink: /user/common-build-problems/
+redirect_from:
+  - /user/build-timeouts/
 ---
 
 <div id="toc"></div>
@@ -196,10 +198,128 @@ This can be done with the follow addition to your `.travis.yml`:
 The above addition will reinstall the en\_US language pack, as well as the de\_DE
 language pack.
 
-## Linux: apt fails to install package with 404 error.
+## Linux: apt fails to install package with 404 error
 
 This is often caused by old package database and can be fixed by adding the following to `.travis.yml`:
 
     before_install:
       - sudo apt-get update
 
+
+## Travis CI does not Preserve State Between Builds
+
+Travis CI uses virtual machine snapshotting to make sure no state is preserved between
+builds. If you modify CI environment by writing something to a data store, creating
+files or installing a package via apt, it does affect subsequent builds.
+
+## SSH is not working as expected
+
+Travis CI runs all commands over SSH in isolated virtual machines. Commands that
+modify SSH session state are "sticky" and persist throughout the build. For example,
+if you `cd` into a directory, all subsequent commands are run from that directory.
+
+## Git Submodules are not updated correctly
+
+Travis CI automatically initializes and updates submodules when there's a `.gitmodules` file in the root of the repository.
+
+To turn this off, set:
+
+```yml
+git:
+  submodules: false
+```
+
+If your project requires specific options for your Git submodules which Travis CI
+does not support out of the box, turn off the automatic integration and use the
+`before_install` hook to initializes and update them.
+
+For example, to update nested submodules:
+
+```yml
+before_install:
+  - git submodule update --init --recursive
+```
+
+## Git cannot clone my Submodules
+
+If your project uses Git submodules, make sure you use public Git URLs. For example, on GitHub, instead of
+
+    [email protected]:someuser/somelibrary.git
+
+use
+
+    https://github.com/someuser/somelibrary.git
+
+Otherwise, Travis CI builders won't be able to clone your project because they don't have your private SSH key.
+
+## My builds are timing out
+
+Builds can unfortunately time out, either during installation of dependencies, or during the build itself, for instance because of a command that's taking a longer amount of time to run while not producing any output.
+
+Our builds have a global timeout and a timeout that's based on the output. If no output is received from a build for 10 minutes, it's assumed to have stalled for unknown reasons and is subsequently killed.
+
+At other times, installation of dependencies can timeout. Bundler and RubyGems are a relevant example. Network connectivity between our servers can sometimes affect connectivity to APT, Maven or other repositories.
+
+There are few ways to work around that.
+
+### Timeouts installing dependencies
+
+Bundler can time out downloading RubyGems or talking to the APIs at rubygems.org. In the same way, pip can be affected by network connectivity issues to the PyPi mirrors or CDN endpoints.
+
+Bundler itself now has a [built-in feature to retry](http://bundler.io/v1.5/bundle_install.html#retry) gem downloads or API calls when a network error or timeout occurs.
+
+You can add the `--retry` option with the number of retries you'd like to use. *Note: this may become a default in the future on Travis CI.*
+
+Here's what you can add to your .travis.yml:
+
+    bundler_args: --retry 3
+
+Beyond Bundler, you can wrap commands using the function `travis_retry` which checks the return code of a command, retrying it three times if the return code is non-zero.
+
+    install: travis_retry bundle install
+
+Note that with Bundler, using one or the other should be sufficient to catch network timeouts affecting your build. Using the new `--retry` option has the benefit of giving you finer control about the total amount of retries.
+
+We recommend using `travis_retry` when you have commands that only install one or two RubyGems, for instance, or when they're timing out for other reasons.
+
+Most of our build-internal commands are wrapped with `travis_retry` to reduce the impact of temporary network hiccups.
+
+### Build times out because no output was received
+
+When a long running command or compile step regularly takes longer than 10 minutes without producing any output, you can adjust your build configuration to take that into consideration.
+
+The shell environment in our build system provides a function that helps to work around that, at least for longer than 10 minutes.
+
+If you have a command that doesn't produce output for more than 10 minutes, you can prefix it with `travis_wait`, a function that's exported by our build environment.
+
+    install: travis_wait mvn install
+
+`travis_wait` writes a short line to the build log every minute for 20 minutes, extending the amount of time your command has to finish.
+
+We recommend careful use of `travis_wait`, as overusing it can extend your build time when there could be a deeper underlying issue. When in doubt, [file a ticket](https://github.com/travis-ci/travis-ci/issues/new) or [email us](mailto:[email protected]) first to see if something could be improved about this particular command first.
+
+## Troubleshooting Locally in a Docker Image
+
+If you're having trouble tracking down the exact problem in a build it often helps to run the build locally. To do this you need to be using our container based infrastructure (ie, have `sudo: false` in your `.travis.yml`), and to know which Docker image you are using on Travis CI.
+
+### Running a Container Based Docker Image Locally
+
+1. Download and install the Docker Engine:
+  * [Windows](https://docs.docker.com/installation/windows)
+  * [OS X](https://docs.docker.com/installation/mac)
+  * [Ubuntu Linux](https://docs.docker.com/installation/ubuntulinux/)
+2. Select an image from [Quay.io](https://quay.io/organization/travisci). If you're not using a language-specific image pick `travis-ruby`. Open a terminal and start an interactive Docker session using the image URL:
+
+   ```bash
+   docker run -it quay.io/travisci/travis-ruby /bin/bash
+   ```
+
+3. Switch to the `travis` user:
+
+   ```bash
+   su - travis
+   ```
+
+3. Clone your git repository into the `/` folder of the image.
+4. Manually install any dependencies.
+5. Manually run your Travis CI build command.

user/common-build-problems.md

@@ -6,6 +6,7 @@ redirect_from:
   - /user/build-configuration/
   - /user/build-lifecycle/
   - /user/how-to-skip-a-build/
+  - /user/repository-providers/
 ---
 
 <div id="toc"></div>
@@ -449,46 +450,14 @@ hostnames in `/etc/hosts` for both IPv4 and IPv6.
         - travis.dev
         - joshkalderimis.com
 
+## What git Repository Providers can I use         
 
-## Build FAQ
+Build and test your open source projects hosted on Github on [travis-ci.org](https://travis-ci.org/).
 
-### Travis CI Preserves No State Between Builds
+Build and test your private repositories hosted on Github on [travis-ci.com](https://travis-ci.com/).
 
-Travis CI uses virtual machine snapshotting to make sure no state is left between builds. If you modify CI environment by writing something to a data store, creating files or installing a package via apt, it won't affect subsequent builds.
+Travis CI currently does not support repositories hosted on Bitbucket, Gitlab or Atlassian Stash.
 
-### SSH
+## Troubleshooting
 
-Travis CI runs all commands over SSH in isolated virtual machines. Commands that modify SSH session state are "sticky" and persist throughout the build.
-For example, if you `cd` into a particular directory, all the following commands will be executed from it. This may be used for good (e.g. building subprojects one
-after another) or affect tools like `rake` or `mvn` that may be looking for files in the current directory.
-
-### Git Submodules
-
-Travis CI automatically initializes and updates submodules when there's a `.gitmodules` file in the root of the repository.
-
-This can be turned off by setting:
-
-    git:
-      submodules: false
-
-If your project requires some specific option for your Git submodules which Travis CI does not support out of the box, then you can turn the automatic integration off and use the `before_install` hook to initializes and update them.
-
-For example:
-
-    before_install:
-      - git submodule update --init --recursive
-
-This will include nested submodules (submodules of submodules), in case there are any.
-
-
-### Use Public URLs For Submodules
-
-If your project uses Git submodules, make sure you use public Git URLs. For example, on GitHub, instead of
-
-    [email protected]:someuser/somelibrary.git
-
-use
-
-    https://github.com/someuser/somelibrary.git
-
-Otherwise, Travis CI builders won't be able to clone your project because they don't have your private SSH key.
+Check out the list of [common build problems](/user/common-build-problems/).

user/customizing-the-build.md

@@ -1,5 +1,5 @@
 ---
-title: Testing Pull Requests
+title: Building Pull Requests
 layout: en
 permalink: /user/pull-requests/
 ---

user/pricing.md

@@ -1,12 +1,14 @@
 ---
-title: Travis Pro - Frequently Asked Questions
+title: Travis Pro
 layout: en
 permalink: /user/travis-pro/
+redirect_from:
+  - /user/pricing/
 ---
 
 <div id="toc"></div>
 
-Note: These issues are related to [Travis Pro](http://travis-ci.com), our hosted
+Learn more about [Travis Pro](http://travis-ci.com), our hosted
 continuous integration solution for private repositories.
 
 ## Can I use pull request testing on Travis Pro?
@@ -35,3 +37,10 @@ You can find more information on this topic in our [Security Statement](https://
 ## How can I encrypt files that include sensitive data?
 
 You can follow our guide for [encrypting files](/user/encrypting-files/).
+
+## Why can't I find information on pricing on [travis-ci.org](https://travis-ci.org)?
+
+Travis CI is, and always will be, free for open source projects.
+
+For a list of plans and prices for private repositories, look at
+[travis-ci.com/plans](https://travis-ci.com/plans).