RubyGems - utopia - Versions diffs - 2.2.0 → 2.3.0 - Mend

utopia 2.2.0 → 2.3.0

Files changed (290) hide show

data/docs/wiki/middleware/session.html ADDED Viewed

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Session - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../_components/jquery/jquery.min.js"></script>
+		<script src="../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="session.html">Session</a></nav>
+	<h1 id="session">Session</h1>
+<p>The session management uses symmetric private key encryption to store data on the client and avoid tampering.</p>
+<pre><code class="language-ruby">use Utopia::Session,
+	:expires_after =&gt; 3600,
+	:secret =&gt; '40 or more random characters for your secret key'
+</code></pre>
+<p>All session data is stored on the client, but it’s encrypted with a salt and the secret key. It would be hard for the client to decrypt the data without the secret.</p>
+<h2 id="using-environmentyaml">Using <code>environment.yaml</code></h2>
+<p>The session secret should not be shared or ideally, not stored in source code. This can be easily achieved using an environment variable, stored in <code>environment.yaml</code> on the production server:</p>
+<pre><code class="language-ruby">use Utopia::Session,
+	:expires_after =&gt; 3600,
+	:secret =&gt; ENV['UTOPIA_SESSION_SECRET']
+</code></pre>
+<p>In development, the secret would be reset every time the server is restarted. To set a fixed secret on production, run the following:</p>
+<pre><code class="language-bash">$ utopia server environment UTOPIA_SESSION_SECRET=$(head /dev/urandom | shasum | base64 | head -c 40)
+</code></pre>
+<p>This is done by default when using <code>utopia server create</code> and <code>utopia server update</code>.</p>
+	<footer>
+		Last Modified: 2017-02-13 16:30:17 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/middleware/session/index.html ADDED Viewed

@@ -0,0 +1,71 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Session - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../../_components/jquery/jquery.min.js"></script>
+		<script src="../../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="../session.html">Session</a></nav>
+	<h1 id="session">Session</h1>
+<p>The session management uses symmetric private key encryption to store data on the client and avoid tampering.</p>
+<pre><code class="language-ruby">use Utopia::Session,
+	:expires_after =&gt; 3600,
+	:secret =&gt; '40 or more random characters for your secret key'
+</code></pre>
+<p>All session data is stored on the client, but it’s encrypted with a salt and the secret key. It would be hard for the client to decrypt the data without the secret.</p>
+<h2 id="using-environmentyaml">Using <code>environment.yaml</code></h2>
+<p>The session secret should not be shared or ideally, not stored in source code. This can be easily achieved using an environment variable, stored in <code>environment.yaml</code> on the production server:</p>
+<pre><code class="language-ruby">use Utopia::Session,
+	:expires_after =&gt; 3600,
+	:secret =&gt; ENV['UTOPIA_SESSION_SECRET']
+</code></pre>
+<p>In development, the secret would be reset every time the server is restarted. To set a fixed secret on production, run the following:</p>
+<pre><code class="language-bash">$ utopia server environment UTOPIA_SESSION_SECRET=$(head /dev/urandom | shasum | base64 | head -c 40)
+</code></pre>
+<p>This is done by default when using <code>utopia server create</code> and <code>utopia server update</code>.</p>
+	<footer>
+		Last Modified: 2017-02-13 16:30:17 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/middleware/static.html ADDED Viewed

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Static - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../_components/jquery/jquery.min.js"></script>
+		<script src="../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="static.html">Static</a></nav>
+	<h1 id="static">Static</h1>
+<p>This middleware serves static files using the <code>mime-types</code> library. By default, it works with <code>Rack::Sendfile</code> and supports <code>ETag</code> based caching. Normally, you’d prefer to put static files into <code>public/_static</code> but it’s also acceptable to put static content into <code>pages/</code> if it makes sense.</p>
+<pre><code class="language-ruby">use Utopia::Static,
+	# The root path to serve files from:
+	root: "path/to/root",
+	# The mime-types to recognize/serve:
+	types: [:default, :xiph],
+	# Cache-Control header for files:
+	cache_control: 'public, max-age=7200'
+</code></pre>
+	<footer>
+		Last Modified: 2016-12-13 12:36:48 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/middleware/static/index.html ADDED Viewed

@@ -0,0 +1,57 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Static - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../../_components/jquery/jquery.min.js"></script>
+		<script src="../../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../../wiki.html">Wiki</a> › <span>Middleware</span> › <a href="../static.html">Static</a></nav>
+	<h1 id="static">Static</h1>
+<p>This middleware serves static files using the <code>mime-types</code> library. By default, it works with <code>Rack::Sendfile</code> and supports <code>ETag</code> based caching. Normally, you’d prefer to put static files into <code>public/_static</code> but it’s also acceptable to put static content into <code>pages/</code> if it makes sense.</p>
+<pre><code class="language-ruby">use Utopia::Static,
+	# The root path to serve files from:
+	root: "path/to/root",
+	# The mime-types to recognize/serve:
+	types: [:default, :xiph],
+	# Cache-Control header for files:
+	cache_control: 'public, max-age=7200'
+</code></pre>
+	<footer>
+		Last Modified: 2016-12-13 12:36:48 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/server-setup.html ADDED Viewed

@@ -0,0 +1,118 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Server Setup - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../_static/icon.png"/>
+		<link rel="stylesheet" href="../_static/site.css" type="text/css" media="screen"/>
+		<script src="../_components/jquery/jquery.min.js"></script>
+		<script src="../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../wiki.html">Wiki</a> › <a href="server-setup.html">Server Setup</a></nav>
+	<h1 id="server-setup">Server Setup</h1>
+<p>Utopia is designed to make deployment to remote servers easy.</p>
+<h2 id="deployment">Deployment</h2>
+<p>The preferred method of deployment to a production server is via git. The <code>utopia</code> command assists with setup of a remote git repository on the server. It will setup a <code>git</code> <code>post-update</code> hook which will deploy the site correctly and restart passenger for that site.</p>
+<p>To setup a server for deployment:</p>
+<pre><code class="language-bash">$ mkdir /srv/http/www.example.com
+$ cd /srv/http/www.example.com
+$ sudo -u http utopia server create
+</code></pre>
+<p>On your development machine, you should setup the git remote:</p>
+<pre><code class="language-bash">$ git remote add production ssh://remote/srv/http/www.example.com
+$ git push --set-upstream production master
+</code></pre>
+<h3 id="default-environment">Default Environment</h3>
+<p>Utopia will load <code>config/environment.yaml</code> and update <code>ENV</code> before executing any code. You can set default environment values using the <code>utopia</code> command:</p>
+<pre><code class="language-bash">$ sudo -u http utopia environment RACK_ENV=production DATABASE_ENV=production_cluster_primary
+ENV["RACK_ENV"] will default to "production" unless otherwise specified.
+ENV["DATABASE_ENV"] will default to "production_cluster_primary" unless otherwise specified.
+</code></pre>
+<p>To set a value, write <code>KEY=VALUE</code>. To unset a key, write <code>KEY</code>.</p>
+<p>When you run <code>rake</code> tasks or spawn a server, the values in <code>config/environment.yaml</code> will be the defaults. You can override them by manually specifying them, e.g. <code>DATABASE_ENV=development rake db:info</code>.</p>
+<h2 id="platform">Platform</h2>
+<p>The best deployment platform for Utopia is Linux. Specifically, <a href="https://www.archlinux.org/">Arch Linux</a> with the following packages:</p>
+<ul>
+  <li><a href="https://aur.archlinux.org/packages/nginx-mainline-passenger/">nginx-mainline-passenger</a></li>
+  <li><a href="https://aur.archlinux.org/packages/passenger-nginx-module/">passenger-nginx-module</a></li>
+</ul>
+<p>There have been issues with the official packages and thus these packages were developed and tested with Utopia deployment in mind.</p>
+<h3 id="sample-nginx-configuration">Sample Nginx Configuration</h3>
+<p>Create a configuration file for your site, e.g. <code>/etc/nginx/sites/www.example.com</code>:</p>
+<pre><code class="language-nginx">server {
+	listen 80;
+	server_name www.example.com;
+	root /srv/http/www.example.com/public;
+	passenger_enabled on;
+}
+server {
+	listen 80;
+	server_name example.com;
+	rewrite ^ http://www.example.com$uri permanent;
+}
+</code></pre>
+<h3 id="sudo-setup">Sudo Setup</h3>
+<p>Create a file <code>/etc/sudoers.d/http</code> with the following contents:</p>
+<pre><code class="language-sudoers"># Allow user samuel to check out code as user http using git:
+%wheel ALL=(http) NOPASSWD: ALL
+</code></pre>
+<p>This allows the deploy task to correctly checkout code as user <code>http</code>.</p>
+	<footer>
+		Last Modified: 2018-03-24 20:49:16 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>

data/docs/wiki/server-setup/index.html ADDED Viewed

@@ -0,0 +1,118 @@
+<!DOCTYPE html>
+<html>
+	<head>
+			<title>Server Setup - Utopia</title>
+		<meta charset="UTF-8"/>
+		<link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-wvfXpqpZZVQGK6TAh5PVlGOfQNHSoD2xbE+QkPxCAFlNEevoEH3Sl0sibVcOQVnN" crossorigin="anonymous"/>
+		<link rel="icon" type="image/png" href="../../_static/icon.png"/>
+		<link rel="stylesheet" href="../../_static/site.css" type="text/css" media="screen"/>
+		<script src="../../_components/jquery/jquery.min.js"></script>
+		<script src="../../_components/jquery-syntax/jquery.syntax.min.js"></script>
+		<script type="text/javascript">
+		//<![CDATA[
+			jQuery(function($) {
+				$.syntax();
+			});
+		//]]>
+		</script>
+	</head>
+	<body class="">
+		<header>
+			<img src="../../_static/utopia.svg"/>
+		</header>
+		<div id="page">
+	<nav>
+	 › <a href="../../wiki.html">Wiki</a> › <a href="../server-setup.html">Server Setup</a></nav>
+	<h1 id="server-setup">Server Setup</h1>
+<p>Utopia is designed to make deployment to remote servers easy.</p>
+<h2 id="deployment">Deployment</h2>
+<p>The preferred method of deployment to a production server is via git. The <code>utopia</code> command assists with setup of a remote git repository on the server. It will setup a <code>git</code> <code>post-update</code> hook which will deploy the site correctly and restart passenger for that site.</p>
+<p>To setup a server for deployment:</p>
+<pre><code class="language-bash">$ mkdir /srv/http/www.example.com
+$ cd /srv/http/www.example.com
+$ sudo -u http utopia server create
+</code></pre>
+<p>On your development machine, you should setup the git remote:</p>
+<pre><code class="language-bash">$ git remote add production ssh://remote/srv/http/www.example.com
+$ git push --set-upstream production master
+</code></pre>
+<h3 id="default-environment">Default Environment</h3>
+<p>Utopia will load <code>config/environment.yaml</code> and update <code>ENV</code> before executing any code. You can set default environment values using the <code>utopia</code> command:</p>
+<pre><code class="language-bash">$ sudo -u http utopia environment RACK_ENV=production DATABASE_ENV=production_cluster_primary
+ENV["RACK_ENV"] will default to "production" unless otherwise specified.
+ENV["DATABASE_ENV"] will default to "production_cluster_primary" unless otherwise specified.
+</code></pre>
+<p>To set a value, write <code>KEY=VALUE</code>. To unset a key, write <code>KEY</code>.</p>
+<p>When you run <code>rake</code> tasks or spawn a server, the values in <code>config/environment.yaml</code> will be the defaults. You can override them by manually specifying them, e.g. <code>DATABASE_ENV=development rake db:info</code>.</p>
+<h2 id="platform">Platform</h2>
+<p>The best deployment platform for Utopia is Linux. Specifically, <a href="https://www.archlinux.org/">Arch Linux</a> with the following packages:</p>
+<ul>
+  <li><a href="https://aur.archlinux.org/packages/nginx-mainline-passenger/">nginx-mainline-passenger</a></li>
+  <li><a href="https://aur.archlinux.org/packages/passenger-nginx-module/">passenger-nginx-module</a></li>
+</ul>
+<p>There have been issues with the official packages and thus these packages were developed and tested with Utopia deployment in mind.</p>
+<h3 id="sample-nginx-configuration">Sample Nginx Configuration</h3>
+<p>Create a configuration file for your site, e.g. <code>/etc/nginx/sites/www.example.com</code>:</p>
+<pre><code class="language-nginx">server {
+	listen 80;
+	server_name www.example.com;
+	root /srv/http/www.example.com/public;
+	passenger_enabled on;
+}
+server {
+	listen 80;
+	server_name example.com;
+	rewrite ^ http://www.example.com$uri permanent;
+}
+</code></pre>
+<h3 id="sudo-setup">Sudo Setup</h3>
+<p>Create a file <code>/etc/sudoers.d/http</code> with the following contents:</p>
+<pre><code class="language-sudoers"># Allow user samuel to check out code as user http using git:
+%wheel ALL=(http) NOPASSWD: ALL
+</code></pre>
+<p>This allows the deploy task to correctly checkout code as user <code>http</code>.</p>
+	<footer>
+		Last Modified: 2018-03-24 20:49:16 +1300 —
+	</footer>
+		</div>
+	</body>
+</html>