Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-18 22:06:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/1.x/Contribs/Contrib-AWSStorage.html
Griatch bbfdf4aff0 Add 1.x legacy docs
2023-12-20 19:01:27 +01:00

355 lines
No EOL
20 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<title>AWSstorage system &#8212; Evennia 1.0 documentation</title>
<link rel="stylesheet" href="../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Building menu" href="Contrib-Building-Menu.html" />
<link rel="prev" title="Guidelines for Evennia contribs" href="Contribs-Guidelines.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Contrib-Building-Menu.html" title="Building menu"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="Contribs-Guidelines.html" title="Guidelines for Evennia contribs"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Contribs-Overview.html" accesskey="U">Contribs</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">AWSstorage system</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<h3><a href="../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">AWSstorage system</a><ul>
<li><a class="reference internal" href="#on-costs">On costs</a></li>
<li><a class="reference internal" href="#technical-details">Technical details</a></li>
<li><a class="reference internal" href="#installation">Installation</a><ul>
<li><a class="reference internal" href="#set-up-aws-account">Set up AWS account</a></li>
</ul>
</li>
<li><a class="reference internal" href="#dependencies">Dependencies</a></li>
<li><a class="reference internal" href="#configure-evennia">Configure Evennia</a></li>
<li><a class="reference internal" href="#check-that-it-works">Check that it works</a></li>
<li><a class="reference internal" href="#uninstallation">Uninstallation</a></li>
<li><a class="reference internal" href="#license">License</a></li>
<li><a class="reference internal" href="#versioning">Versioning</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="Contribs-Guidelines.html"
title="previous chapter">Guidelines for Evennia contribs</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="Contrib-Building-Menu.html"
title="next chapter">Building menu</a></p>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../_sources/Contribs/Contrib-AWSStorage.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div><h3>Links</h3>
<ul>
<li><a href="https://www.evennia.com">Home page</a> </li>
<li><a href="https://github.com/evennia/evennia">Evennia Github</a> </li>
<li><a href="http://games.evennia.com">Game Index</a> </li>
<li>
<a href="https://discord.gg/AJJpcRUhtF">Discord</a> -
<a href="https://github.com/evennia/evennia/discussions">Discussions</a> -
<a href="https://evennia.blogspot.com/">Blog</a>
</li>
</ul>
</div>
</div>
<div class="bodywrapper">
<div class="body" role="main">
<section class="tex2jax_ignore mathjax_ignore" id="awsstorage-system">
<h1>AWSstorage system<a class="headerlink" href="#awsstorage-system" title="Permalink to this headline"></a></h1>
<p>Contrib by The Right Honourable Reverend (trhr), 2020</p>
<p>This plugin migrates the Web-based portion of Evennia, namely images,
javascript, and other items located inside staticfiles into Amazon AWS (S3)
cloud hosting. Great for those serving media with the game.</p>
<p>Files hosted on S3 are “in the cloud,” and while your personal
server may be sufficient for serving multimedia to a minimal number of users,
the perfect use case for this plugin would be:</p>
<ul class="simple">
<li><p>Servers supporting heavy web-based traffic (webclient, etc) …</p></li>
<li><p>With a sizable number of users …</p></li>
<li><p>Where the users are globally distributed …</p></li>
<li><p>Where multimedia files are served to users as a part of gameplay</p></li>
</ul>
<p>Bottom line - if you’re sending an image to a player every time they traverse a
map, the bandwidth reduction of using this will be substantial. If not, probably
skip this contrib.</p>
<section id="on-costs">
<h2>On costs<a class="headerlink" href="#on-costs" title="Permalink to this headline"></a></h2>
<p>Note that storing and serving files via S3 is not technically free outside of
Amazon’s “free tier” offering, which you may or may not be eligible for;
setting up a vanilla evennia server with this contrib currently requires 1.5MB
of storage space on S3, making the current total cost of running this plugin
~$0.0005 per year. If you have substantial media assets and intend to serve
them to many users, caveat emptor on a total cost of ownership - check AWS’s
pricing structure.</p>
</section>
<section id="technical-details">
<h2>Technical details<a class="headerlink" href="#technical-details" title="Permalink to this headline"></a></h2>
<p>This is a drop-in replacement that operates deeper than all of Evennia’s code,
so your existing code does not need to change at all to support it.</p>
<p>For example, when Evennia (or Django), tries to save a file permanently (say, an
image uploaded by a user), the save (or load) communication follows the path:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Evennia -&gt; Django
Django -&gt; Storage backend
Storage backend -&gt; file storage location (e.g. hard drive)
</pre></div>
</div>
<p><a class="reference external" href="https://docs.djangoproject.com/en/3.0/ref/settings/#std:setting-STATICFILES_STORAGE">django docs</a></p>
<p>This plugin, when enabled, overrides the default storage backend,
which defaults to saving files at mygame/website/, instead,
sending the files to S3 via the storage backend defined herein.</p>
<p>There is no way (or need) to directly access or use the functions here with
other contributions or custom code. Simply work how you would normally, Django
will handle the rest.</p>
</section>
<section id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline"></a></h2>
<section id="set-up-aws-account">
<h3>Set up AWS account<a class="headerlink" href="#set-up-aws-account" title="Permalink to this headline"></a></h3>
<p>If you don’t have an AWS S3 account, you should create one at
<a class="reference external" href="https://aws.amazon.com/">https://aws.amazon.com/</a> - documentation for AWS S3 is available at:
<a class="reference external" href="https://docs.aws.amazon.com/AmazonS3/latest/gsg/GetStartedWithS3.html">https://docs.aws.amazon.com/AmazonS3/latest/gsg/GetStartedWithS3.html</a></p>
<p>Credentials required within the app are AWS IAM Access Key and Secret Keys,
which can be generated/found in the AWS Console.</p>
<p>The following example IAM Control Policy Permissions can be added to
the IAM service inside AWS. Documentation for this can be found here:
<a class="reference external" href="https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html">https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html</a></p>
<p>Note that this is only required if you want to tightly secure the roles
that this plugin has access to.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">&quot;Version&quot;</span><span class="p">:</span> <span class="s2">&quot;2012-10-17&quot;</span><span class="p">,</span>
<span class="s2">&quot;Statement&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="s2">&quot;Sid&quot;</span><span class="p">:</span> <span class="s2">&quot;evennia&quot;</span><span class="p">,</span>
<span class="s2">&quot;Effect&quot;</span><span class="p">:</span> <span class="s2">&quot;Allow&quot;</span><span class="p">,</span>
<span class="s2">&quot;Action&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;s3:PutObject&quot;</span><span class="p">,</span>
<span class="s2">&quot;s3:GetObjectAcl&quot;</span><span class="p">,</span>
<span class="s2">&quot;s3:GetObject&quot;</span><span class="p">,</span>
<span class="s2">&quot;s3:ListBucket&quot;</span><span class="p">,</span>
<span class="s2">&quot;s3:DeleteObject&quot;</span><span class="p">,</span>
<span class="s2">&quot;s3:PutObjectAcl&quot;</span>
<span class="p">],</span>
<span class="s2">&quot;Resource&quot;</span><span class="p">:</span> <span class="p">[</span>
<span class="s2">&quot;arn:aws:s3:::YOUR_BUCKET_NAME/*&quot;</span><span class="p">,</span>
<span class="s2">&quot;arn:aws:s3:::YOUR_BUCKET_NAME&quot;</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">],</span>
<span class="p">[</span>
<span class="p">{</span>
<span class="s2">&quot;Sid&quot;</span><span class="p">:</span><span class="s2">&quot;evennia&quot;</span><span class="p">,</span>
<span class="s2">&quot;Effect&quot;</span><span class="p">:</span><span class="s2">&quot;Allow&quot;</span><span class="p">,</span>
<span class="s2">&quot;Action&quot;</span><span class="p">:[</span>
<span class="s2">&quot;s3:CreateBucket&quot;</span><span class="p">,</span>
<span class="p">],</span>
<span class="s2">&quot;Resource&quot;</span><span class="p">:[</span>
<span class="s2">&quot;arn:aws:s3:::*&quot;</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Advanced Users: The second IAM statement, CreateBucket, is only needed
for initial installation. You can remove it later, or you can
create the bucket and set the ACL yourself before you continue.</p>
</section>
</section>
<section id="dependencies">
<h2>Dependencies<a class="headerlink" href="#dependencies" title="Permalink to this headline"></a></h2>
<p>This package requires the dependency “boto3 &gt;= 1.4.4”, the official
AWS python package. To install, it’s easiest to just install Evennia’s
extra requirements;</p>
<ul class="simple">
<li><p>Activate your <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to the root of the Evennia repository. There should be an <code class="docutils literal notranslate"><span class="pre">requirements_extra.txt</span></code>
file here.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">-r</span> <span class="pre">requirements_extra.txt</span></code></p></li>
</ul>
</section>
<section id="configure-evennia">
<h2>Configure Evennia<a class="headerlink" href="#configure-evennia" title="Permalink to this headline"></a></h2>
<p>Customize the variables defined below in <code class="docutils literal notranslate"><span class="pre">secret_settings.py</span></code>. No further
configuration is needed. Note the three lines that you need to set to your
actual values.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="c1"># START OF SECRET_SETTINGS.PY COPY/PASTE &gt;&gt;&gt;</span>
<span class="n">AWS_ACCESS_KEY_ID</span> <span class="o">=</span> <span class="s1">&#39;THIS_IS_PROVIDED_BY_AMAZON&#39;</span>
<span class="n">AWS_SECRET_ACCESS_KEY</span> <span class="o">=</span> <span class="s1">&#39;THIS_IS_PROVIDED_BY_AMAZON&#39;</span>
<span class="n">AWS_STORAGE_BUCKET_NAME</span> <span class="o">=</span> <span class="s1">&#39;mygame-evennia&#39;</span> <span class="c1"># CHANGE ME! I suggest yourgamename-evennia</span>
<span class="c1"># The settings below need to go in secret_settings,py as well, but will</span>
<span class="c1"># not need customization unless you want to do something particularly fancy.</span>
<span class="n">AWS_S3_REGION_NAME</span> <span class="o">=</span> <span class="s1">&#39;us-east-1&#39;</span> <span class="c1"># N. Virginia</span>
<span class="n">AWS_S3_OBJECT_PARAMETERS</span> <span class="o">=</span> <span class="p">{</span> <span class="s1">&#39;Expires&#39;</span><span class="p">:</span> <span class="s1">&#39;Thu, 31 Dec 2099 20:00:00 GMT&#39;</span><span class="p">,</span>
<span class="s1">&#39;CacheControl&#39;</span><span class="p">:</span> <span class="s1">&#39;max-age=94608000&#39;</span><span class="p">,</span> <span class="p">}</span>
<span class="n">AWS_DEFAULT_ACL</span> <span class="o">=</span> <span class="s1">&#39;public-read&#39;</span>
<span class="n">AWS_S3_CUSTOM_DOMAIN</span> <span class="o">=</span> <span class="s1">&#39;</span><span class="si">%s</span><span class="s1">.s3.amazonaws.com&#39;</span> <span class="o">%</span> <span class="n">settings</span><span class="o">.</span><span class="n">AWS_BUCKET_NAME</span>
<span class="n">AWS_AUTO_CREATE_BUCKET</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">STATICFILES_STORAGE</span> <span class="o">=</span> <span class="s1">&#39;evennia.contrib.base_systems.awsstorage.aws-s3-cdn.S3Boto3Storage&#39;</span>
<span class="c1"># &lt;&lt;&lt; END OF SECRET_SETTINGS.PY COPY/PASTE</span>
</pre></div>
</div>
<p>You may also store these keys as environment variables of the same name.
For advanced configuration, refer to the docs for django-storages.</p>
<p>After copying the above, run <code class="docutils literal notranslate"><span class="pre">evennia</span> <span class="pre">reboot</span></code>.</p>
</section>
<section id="check-that-it-works">
<h2>Check that it works<a class="headerlink" href="#check-that-it-works" title="Permalink to this headline"></a></h2>
<p>Confirm that web assets are being served from S3 by visiting your website, then
checking the source of any image (for instance, the logo). It should read
<code class="docutils literal notranslate"><span class="pre">https://your-bucket-name.s3.amazonaws.com/path/to/file</span></code>. If so, the system
works and you shouldn’t need to do anything else.</p>
</section>
<section id="uninstallation">
<h2>Uninstallation<a class="headerlink" href="#uninstallation" title="Permalink to this headline"></a></h2>
<p>If you haven’t made changes to your static files (uploaded images, etc),
you can simply remove the lines you added to <code class="docutils literal notranslate"><span class="pre">secret_settings.py</span></code>. If you
have made changes and want to uninstall at a later date, you can export
your files from your S3 bucket and put them in /static/ in the evennia
directory.</p>
</section>
<section id="license">
<h2>License<a class="headerlink" href="#license" title="Permalink to this headline"></a></h2>
<p>Draws heavily from code provided by django-storages, for which these contributors
are authors:</p>
<p>Marty Alchin (S3)
David Larlet (S3)
Arne Brodowski (S3)
Sebastian Serrano (S3)
Andrew McClain (MogileFS)
Rafal Jonca (FTP)
Chris McCormick (S3 with Boto)
Ivanov E. (Database)
Ariel Núñez (packaging)
Wim Leers (SymlinkOrCopy + patches)
Michael Elsdörfer (Overwrite + PEP8 compatibility)
Christian Klein (CouchDB)
Rich Leland (Mosso Cloud Files)
Jason Christa (patches)
Adam Nelson (patches)
Erik CW (S3 encryption)
Axel Gembe (Hash path)
Waldemar Kornewald (MongoDB)
Russell Keith-Magee (Apache LibCloud patches)
Jannis Leidel (S3 and GS with Boto)
Andrei Coman (Azure)
Chris Streeter (S3 with Boto)
Josh Schneier (Fork maintainer, Bugfixes, Py3K)
Anthony Monthe (Dropbox)
EunPyo (Andrew) Hong (Azure)
Michael Barrientos (S3 with Boto3)
piglei (patches)
Matt Braymer-Hayes (S3 with Boto3)
Eirik Martiniussen Sylliaas (Google Cloud Storage native support)
Jody McIntyre (Google Cloud Storage native support)
Stanislav Kaledin (Bug fixes in SFTPStorage)
Filip Vavera (Google Cloud MIME types support)
Max Malysh (Dropbox large file support)
Scott White (Google Cloud updates)
Alex Watt (Google Cloud Storage patch)
Jumpei Yoshimura (S3 docs)
Jon Dufresne
Rodrigo Gadea (Dropbox fixes)
Martey Dodoo
Chris Rink
Shaung Cheng (S3 docs)
Andrew Perry (Bug fixes in SFTPStorage)</p>
<p>The repurposed code from django-storages is released under BSD 3-Clause,
same as Evennia, so for detailed licensing, refer to the Evennia license.</p>
</section>
<section id="versioning">
<h2>Versioning<a class="headerlink" href="#versioning" title="Permalink to this headline"></a></h2>
<p>This is confirmed to work for Django 2 and Django 3.</p>
<hr class="docutils" />
<p><small>This document page is generated from <code class="docutils literal notranslate"><span class="pre">evennia/contrib/base_systems/awsstorage/README.md</span></code>. Changes to this
file will be overwritten, so edit that file rather than this one.</small></p>
</section>
</section>
</div>
</div>
</div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="Contrib-Building-Menu.html" title="Building menu"
>next</a> |</li>
<li class="right" >
<a href="Contribs-Guidelines.html" title="Guidelines for Evennia contribs"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Evennia 1.0</a> &#187;</li>
<li class="nav-item nav-item-1"><a href="Contribs-Overview.html" >Contribs</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">AWSstorage system</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2022, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink