Difference between revisions of "Automatic Update Site Uploads"

(Automatic Uploads via Travis CI: add more comment warnings)
(Add more warning text and mention the option of modifying bootstrap.js)
Line 10: Line 10:
 
* Logging in to [https://travis-ci.org/auth Travis CI] with your corresponding GitHub account
 
* Logging in to [https://travis-ci.org/auth Travis CI] with your corresponding GitHub account
 
* An [[Special:CreateAccount|account on this wiki]]
 
* An [[Special:CreateAccount|account on this wiki]]
* An [[Special:ChangeUploadPassword|initialized upload password]]. ('''NOTE''' - not the same as your Wiki password)
+
* An [[Special:ChangeUploadPassword|initialized upload password]]. ('''NOTE''' - ''not'' necessarily the same as your Wiki password)
  
 
= Additional resources =
 
= Additional resources =
Line 79: Line 79:
 
and add additional calls to <code>addUpdateSite</code> as needed.
 
and add additional calls to <code>addUpdateSite</code> as needed.
  
== Non-Maven builds ==
+
== Non-Mavenized Files ==
  
Travis CI is capable of building many languages besides Java. If you do not have a <code>pom.xml</code> then you need to replace the following line of your <code>.travis.yml</code>:
+
Travis CI is capable of building many languages besides Java. If can not use Maven with an <code>imagej.app.directory</code> then you need to replace the following line of your <code>.travis.yml</code>:
  
 
<source lang="yaml">
 
<source lang="yaml">
Line 89: Line 89:
 
with a sequence of commands that will move your build artifacts to the appropriate <code>/jars</code> or <code>/plugins</code> directory, as appropriate for your update site.
 
with a sequence of commands that will move your build artifacts to the appropriate <code>/jars</code> or <code>/plugins</code> directory, as appropriate for your update site.
  
{{Warning | '''USE CAUTION HERE''' - you are configuring Travis CI to upload the state of an ImageJ installation to your update site. If your build artifacts are not located in the <code>jars</code> or <code>plugins</code> directory, a clean ImageJ.app will be uploaded - '''effectively removing all content from your update site.'''}}
+
This is also true if you have custom scripts, macros, etc... if these files are not present in the correct locations of the local ImageJ.app, they will appear to have been deleted.
  
 
= Caveats =
 
= Caveats =
 +
 +
{{Warning | '''USE CAUTION HERE''' - you are configuring Travis CI to upload the state of an ImageJ installation to your update site. The current working directory IS the ImageJ.app that will be uploaded. If your build artifacts are not located in the <code>jars</code> or <code>plugins</code> directory, or you don't manually copy scripts to the correct location, ImageJ will see these items as having been deleted - '''effectively removing all content from your update site.'''</br>You can mitigate this danger by customizing your <code>bootstrap.js</code> to download your own update site into the base ImageJ.app; only changes to the update site state will be uploaded.}}
  
 
{{Warning|By default - building the master branch of your repository - your update site will be updated with **every change** to the source code. Although we encourage the master branch to be "[[Development_Lifecycle#Phase_2:_On_master|release ready]]", a safer practice would be to configure Travis CI to [https://docs.travis-ci.com/user/customizing-the-build/#Building-Specific-Branches only build specific branches] - and set it to build [[Reproducible Builds|release versions]] only - e.g. with a release version integration branch.}}
 
{{Warning|By default - building the master branch of your repository - your update site will be updated with **every change** to the source code. Although we encourage the master branch to be "[[Development_Lifecycle#Phase_2:_On_master|release ready]]", a safer practice would be to configure Travis CI to [https://docs.travis-ci.com/user/customizing-the-build/#Building-Specific-Branches only build specific branches] - and set it to build [[Reproducible Builds|release versions]] only - e.g. with a release version integration branch.}}
  
 
{{Warning|Using the Maven-based <code>.travis.yml</code> as suggested implies that you are conforming to the managed dependencies of the parent pom.xml. If you are not staying up-to-date with the ImageJ and Fiji update sites (by using the latest ImageJ or Fiji [[Architecture#Bill_of_Materials|bill of materials]]) then this automation may break your own update site.}}
 
{{Warning|Using the Maven-based <code>.travis.yml</code> as suggested implies that you are conforming to the managed dependencies of the parent pom.xml. If you are not staying up-to-date with the ImageJ and Fiji update sites (by using the latest ImageJ or Fiji [[Architecture#Bill_of_Materials|bill of materials]]) then this automation may break your own update site.}}

Revision as of 03:47, 15 January 2016

Template:UpdateSites



Requirements

Additional resources

Automatic Uploads via Travis CI

Travis CI can be used to automatically build a repository in response to code changes. To ease the maintenance of ImageJ update sites, we can use Travis to automatically upload the latest version of a site. This is done by creating a .travis.yml file in your update site's GitHub repository that does the following:

  1. Create a fresh ImageJ.app
  2. Build the update site's repository and move the required artifacts (e.g. .jars) to their intended locations in the ImageJ.app
  3. Upload the local update site state to your Wiki update site

As a starting point you can copy the following .travis.yml:

language: java
script:
# These first two commands download the bootstrap.js script
# This makes the current directory into a fresh ImageJ.app
# The status of this ImageJ.app will determine what is uploaded to
# your update site. 
  - curl -O http://update.imagej.net/bootstrap.js
  - jrunscript bootstrap.js update-force-pristine
# For a Maven-based project inheriting from pom-imagej, this will
# build the project and install it (and its dependencies) into the
# current ImageJ.app
# WARNING: if you would like any files not built by maven to be on your
#          update site, you must explicitly move them to the appropriate ImageJ.app
#          subdirectory.
  - mvn clean install -Dimagej.app.directory="$(pwd)" -Ddelete.other.versions=true
# Finally, we download and execute script that uploads to the update site
  - curl -O https://raw.githubusercontent.com/fiji/fiji/7f13f66968a9d4622e519c8aae04786db6601314/bin/upload-site-simple.sh
  - chmod a+x upload-site-simple.sh
# TODO: set your update site and upload account as appropriate
  - ./upload-site-simple.sh <UPDATE_SITE> <WIKI_ACCOUNT>
# For example, if your wiki account is IJUser and you're uploading to your personal update site (sites.imagej.net/IJUser) you would use:
# - ./upload-site-simple.sh IJUser IJUser

For the update site and wiki account,

Encrypting your password

To upload to your wiki update site, you will need to provide Travis CI with a WIKI_UPLOAD_PASS environment variable, which should evaluate to the upload password of the Wiki account performing the upload. To do so securely, follow the instructions on the encrypting environment variables.

Note that when you run:

$ travis encrypt WIKI_UPLOAD_PASS=super_secret --add env.matrix

in your repository, the .travis.yml will automatically be updated appropriately. You can simply commit and push the changes.

Add additional update sites

By default, only the ImageJ and Fiji update sites will be enabled in the local ImageJ.app. It's possible to enable additional update sites as needed for your project (for example, if you depend on other 3rd party update sites). To do so, remove the following lines of your .travis.yml:

  - curl -O http://update.imagej.net/bootstrap.js

Instead, you will need to keep a custom copy of bootstrap.js (e.g. in your repository). In this script, find the following line:

		files.addUpdateSite("Fiji", "http://update.fiji.sc/", null, null, -1);

and add additional calls to addUpdateSite as needed.

Non-Mavenized Files

Travis CI is capable of building many languages besides Java. If can not use Maven with an imagej.app.directory then you need to replace the following line of your .travis.yml:

  - mvn clean install -Dimagej.app.directory="$(pwd)" -Ddelete.other.versions=true

with a sequence of commands that will move your build artifacts to the appropriate /jars or /plugins directory, as appropriate for your update site.

This is also true if you have custom scripts, macros, etc... if these files are not present in the correct locations of the local ImageJ.app, they will appear to have been deleted.

Caveats