Skip to content

Commit

Permalink
Folder restructure
Browse files Browse the repository at this point in the history
Remove redundancies
Update README.md and docs
  • Loading branch information
dormant-user committed Sep 21, 2023
1 parent 0dcee65 commit a2d9d17
Show file tree
Hide file tree
Showing 25 changed files with 873 additions and 603 deletions.
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2021 Vignesh Sivanandha Rao
Copyright (c) 2021 Vignesh Rao

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
34 changes: 16 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Expose localhost using EC2
Expose an app/api running on local host to public internet using AWS EC2
Reverse proxy that creates a secure tunnel from public endpoint to locally running web service

### Requirements
- Access to an AWS account and [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) configured.
Expand Down Expand Up @@ -29,7 +29,7 @@ The public DNS names for EC2 instances are long and messy. To avoid that, an `A`

:warning:   Requires an active hosted zone on `route53`.

- **DOMAIN**: Domain name registered using `route53`. *Example: `mywebsite.com`*
- **HOSTED_ZONE**: Hosted zone name registered using `route53`. *Example: `mywebsite.com`*
- **SUBDOMAIN**: Sub-domain that has to be added for the domain name. *Example: `tunnel`*

        :bulb:   `tunnel.mywebsite.com` will be the endpoint to access the localhost from public internet.
Expand All @@ -47,17 +47,17 @@ The public DNS names for EC2 instances are long and messy. To avoid that, an `A`

:warning:   Some web browsers might throw a warning and some might even block a self-signed certificate/private CA.

To manually generate a self-signed cert:

> `openssl req -newkey rsa:2048 -sha256 -nodes -keyout YOURPRIVATE.key -x509 -days 365 -out YOURPUBLIC.pem -subj "/C=US/ST=New York/L=Brooklyn/O=Example Brooklyn Company/CN=YOURDOMAIN.EXAMPLE"`
[OR]

Simply let `expose` create a self-signed SSL certificate and a private key. **(Default behavior)**
`expose` creates a self-signed SSL certificate and a private key by default.

- **EMAIL_ADDRESS**: Email address to create the self-signed SSL and private key. Defaults to `[email protected]`
- **ORGANIZATION**: Organization name for the certificate. Defaults to the AWS endpoint.

**Manually generate self-signed certificate**
> `openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.pem -x509 -days 365 -out public.pem -subj "/C=US/ST=New York/L=Brooklyn/O=Example Brooklyn Company/CN=tunnel.example.com"`
**To verify the generated certificate**
> `openssl x509 -inform pem -in public.pem -noout -text`
</details>

### Usage
Expand All @@ -80,11 +80,9 @@ tunnel = expose.Tunnel()
# Start tunneling
tunnel.start()

# set 'purge' flag to 'True' to delete AWS resources if configuration fails
# set 'purge' flag to 'True' to reclaim AWS resources if configuration fails
# tunnel.start(purge=True)

# sleep or do something else

# Stop tunneling - deletes all AWS resources acquired
tunnel.stop()
```
Expand All @@ -100,11 +98,11 @@ tunnel.stop()
### Limitations
Currently `expose` cannot handle, tunneling multiple port numbers without modifying the following env vars in the `.env` file.
```shell
KEY_PAIR
SECURITY_GROUP
KEY_FILE
CERT_FILE
SERVER_INFO
KEY_PAIR # SSH connection to AWS ec2
KEY_FILE # Private key filename for self signed SSL
CERT_FILE # Public certificate filename for self signed SSL
SERVER_INFO # Filename to dump JSON data with server configuration information
SECURITY_GROUP # Ingress and egress firewall rules to control traffic allowed via VPC
```

## Coding Standards
Expand Down Expand Up @@ -149,6 +147,6 @@ pre-commit run --all-files

## License & copyright

&copy; Vignesh Sivanandha Rao
&copy; Vignesh Rao

Licensed under the [MIT License](https://github.com/thevickypedia/expose/blob/main/LICENSE)
4 changes: 2 additions & 2 deletions doc_gen/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@
# -- Project information -----------------------------------------------------

project = 'Expose'
copyright = '2021, Vignesh Sivanandha Rao'
author = 'Vignesh Sivanandha Rao'
copyright = '2021, Vignesh Rao'
author = 'Vignesh Rao'

# -- General configuration ---------------------------------------------------

Expand Down
60 changes: 39 additions & 21 deletions doc_gen/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Expose's documentation!
==================================
Expose - Expose a web service on localhost to public internet using AWS EC2
===========================================================================

.. toctree::
:maxdepth: 2
Expand All @@ -19,46 +19,64 @@ Expose - Main Module
:members:
:undoc-members:

Expose - Configuration
======================
Expose - Auxiliary
==================

.. automodule:: expose.helpers.server
.. automodule:: expose.models.auxiliary
:members:
:undoc-members:

Expose - Route53
================
Expose - Certificates
=====================

.. automodule:: expose.helpers.route_53
.. automodule:: expose.models.cert
:members:
:undoc-members:

Expose - Auxiliary
==================
Expose - Configuration
======================

.. automodule:: expose.helpers.auxiliary
.. autoclass:: expose.models.config.AWSDefaults(pydantic.BaseModel)
:members:
:undoc-members:
:exclude-members: _abc_impl, model_config, model_fields

Expose - Certificates
=====================
====

.. automodule:: expose.helpers.cert
.. autoclass:: expose.models.config.EnvConfig(pydantic_settings.BaseSettings)
:members:
:undoc-members:
:exclude-members: _abc_impl, model_config, model_fields

Expose - AWS Defaults
=====================
====

.. autoclass:: expose.models.config.Settings(pydantic.BaseModel)
:members:
:exclude-members: _abc_impl, model_config, model_fields

.. automodule:: expose.helpers.defaults
Expose - Exceptions
===================

.. automodule:: expose.models.exceptions
:members:
:undoc-members:
:exclude-members: DEFAULT_AMI_NAME, IMAGE_MAP

Expose - LOGGER
===============

.. automodule:: expose.helpers.logger
.. automodule:: expose.models.logger
:members:
:undoc-members:

Expose - Route53
================

.. automodule:: expose.models.route_53
:members:
:undoc-members:

Expose - Server Configuration
=============================

.. automodule:: expose.models.server
:members:
:undoc-members:

Expand Down
45 changes: 23 additions & 22 deletions docs/README.html
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@

<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Welcome to Expose’s documentation!" href="index.html" />
<link rel="prev" title="Expose - Expose a web service on localhost to public internet using AWS EC2" href="index.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
Expand All @@ -30,7 +30,7 @@ <h3>Navigation</h3>
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to Expose’s documentation!"
<a href="index.html" title="Expose - Expose a web service on localhost to public internet using AWS EC2"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Expose documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Expose localhost using EC2</a></li>
Expand All @@ -44,7 +44,7 @@ <h3>Navigation</h3>

<section id="expose-localhost-using-ec2">
<h1>Expose localhost using EC2<a class="headerlink" href="#expose-localhost-using-ec2" title="Permalink to this heading"></a></h1>
<p>Expose an app/api running on local host to public internet using AWS EC2</p>
<p>Reverse proxy that creates a secure tunnel from public endpoint to locally running web service</p>
<section id="requirements">
<h2>Requirements<a class="headerlink" href="#requirements" title="Permalink to this heading"></a></h2>
<ul class="simple">
Expand Down Expand Up @@ -76,7 +76,7 @@ <h3>Environment Variables:<a class="headerlink" href="#environment-variables" ti
<summary><strong>Setup a custom endpoint</strong></summary><p>The public DNS names for EC2 instances are long and messy. To avoid that, an <code class="docutils literal notranslate"><span class="pre">A</span></code> record can be added to the <code class="docutils literal notranslate"><span class="pre">route53</span></code> hosted zone.</p>
<p>:warning:   Requires an active hosted zone on <code class="docutils literal notranslate"><span class="pre">route53</span></code>.</p>
<ul class="simple">
<li><p><strong>DOMAIN</strong>: Domain name registered using <code class="docutils literal notranslate"><span class="pre">route53</span></code>. <em>Example: <code class="docutils literal notranslate"><span class="pre">mywebsite.com</span></code></em></p></li>
<li><p><strong>HOSTED_ZONE</strong>: Hosted zone name registered using <code class="docutils literal notranslate"><span class="pre">route53</span></code>. <em>Example: <code class="docutils literal notranslate"><span class="pre">mywebsite.com</span></code></em></p></li>
<li><p><strong>SUBDOMAIN</strong>: Sub-domain that has to be added for the domain name. <em>Example: <code class="docutils literal notranslate"><span class="pre">tunnel</span></code></em></p></li>
</ul>
<p>        :bulb:   <code class="docutils literal notranslate"><span class="pre">tunnel.mywebsite.com</span></code> will be the endpoint to access the localhost from public internet.</p>
Expand All @@ -91,16 +91,19 @@ <h3>Certificate:<a class="headerlink" href="#certificate" title="Permalink to th
</ul>
<details>
<summary><strong>Generate self-signed SSL certificate</strong></summary><p>:warning:   Some web browsers might throw a warning and some might even block a self-signed certificate/private CA.</p>
<p>To manually generate a self-signed cert:</p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">openssl</span> <span class="pre">req</span> <span class="pre">-newkey</span> <span class="pre">rsa:2048</span> <span class="pre">-sha256</span> <span class="pre">-nodes</span> <span class="pre">-keyout</span> <span class="pre">YOURPRIVATE.key</span> <span class="pre">-x509</span> <span class="pre">-days</span> <span class="pre">365</span> <span class="pre">-out</span> <span class="pre">YOURPUBLIC.pem</span> <span class="pre">-subj</span> <span class="pre">&quot;/C=US/ST=New</span> <span class="pre">York/L=Brooklyn/O=Example</span> <span class="pre">Brooklyn</span> <span class="pre">Company/CN=YOURDOMAIN.EXAMPLE&quot;</span></code></p>
</div></blockquote>
<p>[OR]</p>
<p>Simply let <code class="docutils literal notranslate"><span class="pre">expose</span></code> create a self-signed SSL certificate and a private key. <strong>(Default behavior)</strong></p>
<p><code class="docutils literal notranslate"><span class="pre">expose</span></code> creates a self-signed SSL certificate and a private key by default.</p>
<ul class="simple">
<li><p><strong>EMAIL_ADDRESS</strong>: Email address to create the self-signed SSL and private key. Defaults to <code class="docutils literal notranslate"><span class="pre">USER&#64;expose-localhost.com</span></code></p></li>
<li><p><strong>ORGANIZATION</strong>: Organization name for the certificate. Defaults to the AWS endpoint.</p></li>
</ul>
<p><strong>Manually generate self-signed certificate</strong></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">openssl</span> <span class="pre">req</span> <span class="pre">-newkey</span> <span class="pre">rsa:2048</span> <span class="pre">-sha256</span> <span class="pre">-nodes</span> <span class="pre">-keyout</span> <span class="pre">private.pem</span> <span class="pre">-x509</span> <span class="pre">-days</span> <span class="pre">365</span> <span class="pre">-out</span> <span class="pre">public.pem</span> <span class="pre">-subj</span> <span class="pre">&quot;/C=US/ST=New</span> <span class="pre">York/L=Brooklyn/O=Example</span> <span class="pre">Brooklyn</span> <span class="pre">Company/CN=tunnel.example.com&quot;</span></code></p>
</div></blockquote>
<p><strong>To verify the generated certificate</strong></p>
<blockquote>
<div><p><code class="docutils literal notranslate"><span class="pre">openssl</span> <span class="pre">x509</span> <span class="pre">-inform</span> <span class="pre">pem</span> <span class="pre">-in</span> <span class="pre">public.pem</span> <span class="pre">-noout</span> <span class="pre">-text</span></code></p>
</div></blockquote>
</details></section>
</section>
<section id="usage">
Expand All @@ -125,11 +128,9 @@ <h3>Tunneling:<a class="headerlink" href="#tunneling" title="Permalink to this h
<span class="c1"># Start tunneling</span>
<span class="n">tunnel</span><span class="o">.</span><span class="n">start</span><span class="p">()</span>

<span class="c1"># set &#39;purge&#39; flag to &#39;True&#39; to delete AWS resources if configuration fails</span>
<span class="c1"># set &#39;purge&#39; flag to &#39;True&#39; to reclaim AWS resources if configuration fails</span>
<span class="c1"># tunnel.start(purge=True)</span>

<span class="c1"># sleep or do something else</span>

<span class="c1"># Stop tunneling - deletes all AWS resources acquired</span>
<span class="n">tunnel</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span>
</pre></div>
Expand All @@ -144,11 +145,11 @@ <h3>Tunneling:<a class="headerlink" href="#tunneling" title="Permalink to this h
<section id="limitations">
<h2>Limitations<a class="headerlink" href="#limitations" title="Permalink to this heading"></a></h2>
<p>Currently <code class="docutils literal notranslate"><span class="pre">expose</span></code> cannot handle, tunneling multiple port numbers without modifying the following env vars in the <code class="docutils literal notranslate"><span class="pre">.env</span></code> file.</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>KEY_PAIR
SECURITY_GROUP
KEY_FILE
CERT_FILE
SERVER_INFO
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>KEY_PAIR<span class="w"> </span><span class="c1"># SSH connection to AWS ec2</span>
KEY_FILE<span class="w"> </span><span class="c1"># Private key filename for self signed SSL</span>
CERT_FILE<span class="w"> </span><span class="c1"># Public certificate filename for self signed SSL</span>
SERVER_INFO<span class="w"> </span><span class="c1"># Filename to dump JSON data with server configuration information</span>
SECURITY_GROUP<span class="w"> </span><span class="c1"># Ingress and egress firewall rules to control traffic allowed via VPC</span>
</pre></div>
</div>
</section>
Expand Down Expand Up @@ -194,7 +195,7 @@ <h3>Runbook<a class="headerlink" href="#runbook" title="Permalink to this headin
</section>
<section id="license-copyright">
<h2>License &amp; copyright<a class="headerlink" href="#license-copyright" title="Permalink to this heading"></a></h2>
<p>© Vignesh Sivanandha Rao</p>
<p>© Vignesh Rao</p>
<p>Licensed under the <a class="reference external" href="https://github.com/thevickypedia/expose/blob/main/LICENSE">MIT License</a></p>
</section>
</section>
Expand Down Expand Up @@ -238,7 +239,7 @@ <h3><a href="index.html">Table of Contents</a></h3>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="index.html"
title="previous chapter">Welcome to Expose’s documentation!</a></p>
title="previous chapter">Expose - Expose a web service on localhost to public internet using AWS EC2</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
Expand Down Expand Up @@ -271,14 +272,14 @@ <h3>Navigation</h3>
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="index.html" title="Welcome to Expose’s documentation!"
<a href="index.html" title="Expose - Expose a web service on localhost to public internet using AWS EC2"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Expose documentation</a> &#187;</li>
<li class="nav-item nav-item-this"><a href="">Expose localhost using EC2</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2021, Vignesh Sivanandha Rao.
&#169; Copyright 2021, Vignesh Rao.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 5.1.1.
</div>
</body>
Expand Down
34 changes: 16 additions & 18 deletions docs/_sources/README.md.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Expose localhost using EC2
Expose an app/api running on local host to public internet using AWS EC2
Reverse proxy that creates a secure tunnel from public endpoint to locally running web service

### Requirements
- Access to an AWS account and [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) configured.
Expand Down Expand Up @@ -29,7 +29,7 @@ The public DNS names for EC2 instances are long and messy. To avoid that, an `A`

:warning: &nbsp; Requires an active hosted zone on `route53`.

- **DOMAIN**: Domain name registered using `route53`. *Example: `mywebsite.com`*
- **HOSTED_ZONE**: Hosted zone name registered using `route53`. *Example: `mywebsite.com`*
- **SUBDOMAIN**: Sub-domain that has to be added for the domain name. *Example: `tunnel`*

&nbsp; &nbsp; &nbsp; &nbsp; :bulb: &nbsp; `tunnel.mywebsite.com` will be the endpoint to access the localhost from public internet.
Expand All @@ -47,17 +47,17 @@ The public DNS names for EC2 instances are long and messy. To avoid that, an `A`

:warning: &nbsp; Some web browsers might throw a warning and some might even block a self-signed certificate/private CA.

To manually generate a self-signed cert:

> `openssl req -newkey rsa:2048 -sha256 -nodes -keyout YOURPRIVATE.key -x509 -days 365 -out YOURPUBLIC.pem -subj "/C=US/ST=New York/L=Brooklyn/O=Example Brooklyn Company/CN=YOURDOMAIN.EXAMPLE"`

[OR]

Simply let `expose` create a self-signed SSL certificate and a private key. **(Default behavior)**
`expose` creates a self-signed SSL certificate and a private key by default.

- **EMAIL_ADDRESS**: Email address to create the self-signed SSL and private key. Defaults to `[email protected]`
- **ORGANIZATION**: Organization name for the certificate. Defaults to the AWS endpoint.

**Manually generate self-signed certificate**
> `openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.pem -x509 -days 365 -out public.pem -subj "/C=US/ST=New York/L=Brooklyn/O=Example Brooklyn Company/CN=tunnel.example.com"`

**To verify the generated certificate**
> `openssl x509 -inform pem -in public.pem -noout -text`

</details>

### Usage
Expand All @@ -80,11 +80,9 @@ tunnel = expose.Tunnel()
# Start tunneling
tunnel.start()

# set 'purge' flag to 'True' to delete AWS resources if configuration fails
# set 'purge' flag to 'True' to reclaim AWS resources if configuration fails
# tunnel.start(purge=True)

# sleep or do something else

# Stop tunneling - deletes all AWS resources acquired
tunnel.stop()
```
Expand All @@ -100,11 +98,11 @@ tunnel.stop()
### Limitations
Currently `expose` cannot handle, tunneling multiple port numbers without modifying the following env vars in the `.env` file.
```shell
KEY_PAIR
SECURITY_GROUP
KEY_FILE
CERT_FILE
SERVER_INFO
KEY_PAIR # SSH connection to AWS ec2
KEY_FILE # Private key filename for self signed SSL
CERT_FILE # Public certificate filename for self signed SSL
SERVER_INFO # Filename to dump JSON data with server configuration information
SECURITY_GROUP # Ingress and egress firewall rules to control traffic allowed via VPC
```

## Coding Standards
Expand Down Expand Up @@ -149,6 +147,6 @@ pre-commit run --all-files

## License & copyright

&copy; Vignesh Sivanandha Rao
&copy; Vignesh Rao

Licensed under the [MIT License](https://github.com/thevickypedia/expose/blob/main/LICENSE)
Loading

0 comments on commit a2d9d17

Please sign in to comment.