mirror of
https://github.com/evennia/evennia.git
synced 2026-03-18 13:56:30 +01:00
377 lines
No EOL
20 KiB
HTML
377 lines
No EOL
20 KiB
HTML
|
||
<!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 — Evennia 2.x 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 2.x</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="Contribs-Overview.html" accesskey="U">Contribs</a> »</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/docs/latest/index.html">Documentation Top</a> </li>
|
||
<li><a href="https://www.evennia.com">Evennia Home</a> </li>
|
||
<li><a href="https://github.com/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>
|
||
<h3>Doc Versions</h3>
|
||
<ul>
|
||
|
||
<li><a href="Contrib-AWSStorage.html">2.x (main branch)</a></li>
|
||
<ul>
|
||
<li><a href="../1.3.0/index.html">1.3.0 (v1.3.0 branch)</a></li>
|
||
|
||
<li><a href="../0.9.5/index.html">0.9.5 (v0.9.5 branch)</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 -> Django
|
||
Django -> Storage backend
|
||
Storage backend -> file storage location (e.g. hard drive)
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference external" href="https://docs.djangoproject.com/en/4.1/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">"Version"</span><span class="p">:</span> <span class="s2">"2012-10-17"</span><span class="p">,</span>
|
||
<span class="s2">"Statement"</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="p">{</span>
|
||
<span class="s2">"Sid"</span><span class="p">:</span> <span class="s2">"evennia"</span><span class="p">,</span>
|
||
<span class="s2">"Effect"</span><span class="p">:</span> <span class="s2">"Allow"</span><span class="p">,</span>
|
||
<span class="s2">"Action"</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="s2">"s3:PutObject"</span><span class="p">,</span>
|
||
<span class="s2">"s3:GetObjectAcl"</span><span class="p">,</span>
|
||
<span class="s2">"s3:GetObject"</span><span class="p">,</span>
|
||
<span class="s2">"s3:ListBucket"</span><span class="p">,</span>
|
||
<span class="s2">"s3:DeleteObject"</span><span class="p">,</span>
|
||
<span class="s2">"s3:PutObjectAcl"</span>
|
||
<span class="p">],</span>
|
||
<span class="s2">"Resource"</span><span class="p">:</span> <span class="p">[</span>
|
||
<span class="s2">"arn:aws:s3:::YOUR_BUCKET_NAME/*"</span><span class="p">,</span>
|
||
<span class="s2">"arn:aws:s3:::YOUR_BUCKET_NAME"</span>
|
||
<span class="p">]</span>
|
||
<span class="p">}</span>
|
||
<span class="p">],</span>
|
||
<span class="p">[</span>
|
||
<span class="p">{</span>
|
||
<span class="s2">"Sid"</span><span class="p">:</span><span class="s2">"evennia"</span><span class="p">,</span>
|
||
<span class="s2">"Effect"</span><span class="p">:</span><span class="s2">"Allow"</span><span class="p">,</span>
|
||
<span class="s2">"Action"</span><span class="p">:[</span>
|
||
<span class="s2">"s3:CreateBucket"</span><span class="p">,</span>
|
||
<span class="p">],</span>
|
||
<span class="s2">"Resource"</span><span class="p">:[</span>
|
||
<span class="s2">"arn:aws:s3:::*"</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 >= 1.4.4”, the official
|
||
AWS python package. To install, it’s easiest to just install Evennia’s
|
||
extra requirements;</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>pip install evennia[extra]
|
||
</pre></div>
|
||
</div>
|
||
<p>If you installed Evennia with <code class="docutils literal notranslate"><span class="pre">git</span></code>, you can also</p>
|
||
<ul class="simple">
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to the root of the Evennia repository.</p></li>
|
||
<li><p><code class="docutils literal notranslate"><span class="pre">pip</span> <span class="pre">install</span> <span class="pre">--upgrade</span> <span class="pre">-e</span> <span class="pre">.[extra]</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 >>></span>
|
||
|
||
<span class="n">AWS_ACCESS_KEY_ID</span> <span class="o">=</span> <span class="s1">'THIS_IS_PROVIDED_BY_AMAZON'</span>
|
||
<span class="n">AWS_SECRET_ACCESS_KEY</span> <span class="o">=</span> <span class="s1">'THIS_IS_PROVIDED_BY_AMAZON'</span>
|
||
<span class="n">AWS_STORAGE_BUCKET_NAME</span> <span class="o">=</span> <span class="s1">'mygame-evennia'</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">'us-east-1'</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">'Expires'</span><span class="p">:</span> <span class="s1">'Thu, 31 Dec 2099 20:00:00 GMT'</span><span class="p">,</span>
|
||
<span class="s1">'CacheControl'</span><span class="p">:</span> <span class="s1">'max-age=94608000'</span><span class="p">,</span> <span class="p">}</span>
|
||
<span class="n">AWS_DEFAULT_ACL</span> <span class="o">=</span> <span class="s1">'public-read'</span>
|
||
<span class="n">AWS_S3_CUSTOM_DOMAIN</span> <span class="o">=</span> <span class="s1">'</span><span class="si">%s</span><span class="s1">.s3.amazonaws.com'</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">'evennia.contrib.base_systems.awsstorage.aws-s3-cdn.S3Boto3Storage'</span>
|
||
|
||
<span class="c1"># <<< 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 2.x</a> »</li>
|
||
<li class="nav-item nav-item-1"><a href="Contribs-Overview.html" >Contribs</a> »</li>
|
||
<li class="nav-item nav-item-this"><a href="">AWSstorage system</a></li>
|
||
</ul>
|
||
</div>
|
||
|
||
|
||
|
||
<div class="footer" role="contentinfo">
|
||
© Copyright 2023, The Evennia developer community.
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
|
||
</div>
|
||
</body>
|
||
</html> |