first commit

1 files changed, 178 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..d723a5c
--- /dev/null
+++ b/README
@@ -0,0 +1,178 @@
+# EZCMS - a minimal and simple way to manage a website
+
+## Requirements
+
+Python 3.7+
+
+
+## Huh/What/Why?
+
+EZCMS (or "Easy CMS" for those of you who call that "zed" instead) is a minimal
+and simple way of managing content and serving static files on a website. It
+was mostly made for my own website which I wanted to be simple, but with some
+ability to easily add new pages in a template I like.
+
+EZCMS is designed around the idea that web servers are really just glorified
+file cabinets and draws heavily from the Unix philosophy of "everything is a
+file". When a user finds a site managed by this program, they are primarily
+greeted with a series of folders and files, but in a neat and easy to
+understand index. Each folder--preferably labeled appropriately so users
+know what they're links to other sites--will index itself on click, containing
+a short description of the directory, sub-directories, files, and links
+elsewhere.
+
+Why not just use a database or the million other CMS software packages out
+there? Zero reason not to! I just wanted to see what it would look like to
+build something from the ground up WITHOUT having to copy HTML over and over
+again. Databases are great, but so are filesystems, and I see no reason to
+overcomplicate when making a simple home page. This software is primarily
+geared towards bloggers or people who want a home page like it's 1999, but
+Flask has great documentation so I think you'll find it a pleasure to build on
+top of.
+
+
+## Quick start
+
+It's recommended to run each server in it's own virtual environment. This
+program uses python 3.7, so change `python` to either `python3` or `python3.7`
+depending on your needs. First clone this repo (with git clone, or download the
+zip), change into the directory, then:
+
+
+`python -m venv env`  
+`pip install -r requirements.txt`  
+`python server.py`  
+
+
+Your server will (by default) be hosted on http://localhost:8000
+
+
+## Adding Pages
+
+To add a new page, all you need to do is add a new file (or a folder and a
+group of files) somewhere under one of the folders in `site`. This folder in
+particular is special since it contains the top-level folders which will be
+used to navigate your site, but any folders beneath will be automatically
+indexed.
+
+As an excercise, add a file to the `templates/site/thoughts/rants` folder
+called `myrant.html` and put the following content:
+
+`<p>I don't like spam!</p>`
+
+The new page will be rendered with your navbar on top and footer on the bottom
+when navigated to in the `rants folder` HTML files will by default be rendered
+in page, and all other types of files (like txt) will be returned without
+rendering.
+
+An important note, since these HTML files are being rendered by Flask,
+*you can make full use of the Jinja templating language*! So in other words,
+any template you've developed for flask is fully usable here--but remember it
+will be rendered *inside* the `templates/base.html` template. If you need to
+make tweaks to the navbar or footer, you'll want to edit that file instead.
+
+
+## Customization (or things you'll want to change right now)
+
+To make customization easier, this program comes with a configuration file with
+variables to tweak the display of your site call `siteconfig.py`.
+For example by default this program makes the navbar out of the directories in
+the `templates/site` directory, but you might want include other directories,
+or even external sites. Examples of how to change these options are provided
+in the comments on that file. Customization is also provided through the use of
+specific files.
+
+
+### Navbar customization
+
+Be default, the top navbar is populated by indexing and sorting the top-level
+`templates/site/` directory. You can override this to include any directories
+you want in any order, so long as they exist, but it's advised to still keep
+them all in the `site` directory to avoid confusion.
+
+
+### Index File Configuration
+
+This program uses a single master index file which is used when navigating to
+any directory--instead of having to put in an 'index.html' in each folder, or
+using the default apache/nginx/httpd auto-indexer. In it's place, you can
+optionally put a `.description` file to provide a short description of what's
+in the directory or a `.links` file
+
+The `.description` file should just be a text file with no formatting. If you
+want to add formatting, you can edit the `templates\index.html` file around the
+`{{ description }}` variable (for example, you could wrap it in <i></i> for
+*italics*
+
+The `.links` file is a pseudo-csv file which should contain a comma separated
+list containing a description and a relative or absolute URL to be linked. For
+example this line:
+
+`About,/about`
+
+Produces (roughly) the following HTML on your index page:
+
+`<li><a href="/about">About</a></li>`
+
+You can of course link to external sites, but you must specify the protocol
+(i.e. https://google.com, not google.com). Otherwise, it will be interpreted as
+a relative path like `example.net/google.com`.
+
+
+### Making Secret Directories and Files
+
+This program follows the Unix convention of placing a "." before directories
+and files to make them hidden. Aside from the special files mentioned above,
+this program will not index any file or directory with a "." prepended--and a
+user will receive a 404 error if they attempt to do so.
+
+
+### Mimetype Configuration
+
+Default mime types are primarily sourced from this page with some of my own
+additions for common source code files (like .c or .py):
+
+https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types
+
+You can add your own by editing the 'mimetypes.csv' file in the following
+format:
+
+`.file_extension,type/yourcoolmimetype`
+
+Otherwise, the default mime type is `application/octet-stream`, which (for most
+browsers) triggers the browser to download the file
+
+
+### License Configuration
+
+The default license type is the same as this program's: CC0. The HTML is from
+Creative Commons, with some modifications I like to add. You can of course
+replace the HTML with your own license (or none), by editing
+`templates/site/license.html`
+
+
+### Other tips
+
+There are a few special directories linked that are needed to
+customize your site. First the `static` directory, which holds your static
+files like CSS templates and images. Second the `raw` directory, which allows
+the user to access files the `templates/site` as raw files instead of HTML. 
+You can disable it by deleting the code under `send_file_from_site` or 
+`send_file_from_static` in `server.py`.
+
+
+## Deploying a server
+
+You should NOT run this server as in the quick start, but instead deploy it in
+an appropriate container. Refer to https://flask.palletsprojects.com/en/2.0.x/deploying/
+for options, but an easy option I like is to use uswgi. On a Debian-like distro
+
+
+`sudo apt install uwsgi`  
+`python -m venv env`  
+`uwsgi -s /tmp/yourapplication.sock --manage-script-name --mount /yourapplication=server:app`  
+
+Then point your main http daemon (niginx, apache, httpd) to the socket you
+made. See nginx as an example here, more in the same doc:
+
+https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html