====== Installing Web2Py on DreamHost ======

<WRAP important>\\ **Under construction!**</WRAP>

  * For starters, see the README file at https://github.com/web2py/web2py.
  * Create a fully-hosted domain at [[https://panel.dreamhost.com|DreamHost]].  I used web2py.bikmort.com.
  * Site configuration options include: Remove WWW from beginning of name; use PHP 5.6 FastCGI (default) and Passenger.
  * Since DreamHost uses Passenger as its web app server, extra steps are required to get Web2Py working.
  * Use a shell account to open a terminal window on your DreamHost server.
  * Create a virtual python environment in ~/python (could go elsewhere, but remember the path):

  $ cd ~
  $ virtualenv python
  $ source python/bin/activate
  $ pip install requests  # needed by cams app and others

  * Clone sources from the Web2Py github site((You might prefer to go to github.com and create a fork of the Web2Py sources, then clone your fork.  That's what all the cool kids do.)) into web-server directory (using web2py.bikmort.com as an example):

  $ git clone --recursive https://github.com/web2py/web2py.git web2py.bikmort.com

  * To update to latest Web2Py later (from within web-server directory):

  $ cd ~/web2py.bikmort.com
  $ git pull --recurse-submodules

  * Copy handlers/wsgihandler.py to ./passenger_wsgi.py and edit:

  $ cp handlers/wsgihandler.py passenger_wsgi.py

  * Insert these two lines at around line 40 in passenger_wsgi.py (before call to os.path.isdir):

  INTERP = os.path.join(os.environ['HOME'], 'python', 'bin', 'python')
  if sys.executable != INTERP: os.execl(INTERP, INTERP, *sys.argv)

  * Note that the INTERP path points to the virtualenv-created executable created earlier.
  * Create tmp/restart.txt.  Touch this file to force relaunch of Web2Py via Passenger.

The Web2Py environment should now be operational.  Visit the domain created earlier to see it.

===== Notes =====

  * There are two branches in the top-level repository: master (the standard Web2Py version) and dreamhost (the additions to run it on DreamHost).
  * To see the differences, use "git diff master" (assuming "dreamhost" is current branch).
  * Use "git merge master" to pull changes to the master into the dreamhost branch.

===== Example: WDW =====

  * An empty WDW application at https://bitbucket.org/jtkorb/wdw.
  * Clone into applications directory and it (should be) ready to go.
  * Current model is to develop on laptop, test locally, commit changes, ssh to DreamHost server, and pull changes to applications/wdw directory.

===== Sending Email from Web2Py Using Google G Suite =====

  * These steps do not currently (1/8/2017) appear to work reliably (Google-imposed security concerns).  Should find a better way to send email.
  * Edit applications/appname/private/appconfig.ini
  * Login: email-login:password
  * Use SSL with port 465
  * At Google-app admin site: allow insecure applications and disable captcha.

===== Remote Admin Access =====

These steps allow remote browser access to the Web2Py administrative control panels (both the master panel at ''admin'' as well as the app-specific panels at ''MYAPP/appadmin''.

  * Enable https from the DreamHost [[https://panel.dreamhost.com/index.cgi?tree=domain.manage|domain management panel]].
  * The free certificate from "Let's Encrypt SSL" works.
  * Wait for a few minutes for the certificate to get created and installed.
  * Restart the web server by touching tmp/restart.txt.
  * Set an admin password.

  $ python web2py.py -p 443 -a "secret-secure-password"

This command will give errors (for among other reasons, a user process cannot listen on port 443), but it will have generated the necessary ''parameters_443.py'' file.
  
To redirect all accesses to be via https, there are two options:
  - Use an .htaccess file to do a redirect as described by DreamHost [[https://help.dreamhost.com/hc/en-us/articles/215747758-How-do-I-force-my-site-to-load-securely-with-an-htaccess-file-|here]].
  - Use Web2Py Auth(..., secure=True) setting, but note that this change breaks Travis CI testing.

In either case, there might be cached browser files that break the redirect, for example, redirecting http://www.mysite.com/myapp to https://www.mysite.com/public/myapp.  Verify by opening an incognito window; fix by clearing cached files in the browser.