path: root/README

# 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.


### Why not just neocities?

Neocities is awesome! You should definitely host a site there.

https://neocities.org/

It's easy to get a simple static site going there and it's totally free, but it
lacks server side scripting and a truly self-hosted option. This program gives
you a nice static base to start from, with the ability to script up you own
templates and whatever else Flask has to offer.


## 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:

```bash
$ python -m venv env
$ source env/bin/activate
$ pip install -r requirements.txt
$ python server.py
```

Your server will (by default) be hosted on http://127.0.0.1:5000


## 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`.


### Override base template

Have a page with custom CSS, or need to get rid of the navbar entirely? No
worries! Just add a '!' at the end of you html file and EZCMS will interpret it
as it's own Jinja template without adding everything from the base template.
Tip: if you're just changing the CSS, you can start with the following
boilerplate:

```code
{% extends 'base.html' %}
{% block css%}
//your cool css here
{% endblock %}
{% block content %}
//your cool content here
{% endblock %}
```


### 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 uwsgi since it's well
documented.

```bash
$ sudo pip install uwsgi
$ uwsgi -s /var/path/to/your-flask.sock --manage-script-name --mount /=server:app --virtualenv ./env
```

Then point your main http daemon (niginx, apache, httpd) to the socket you
made. There are examples for a nginx configuration in the uWSGI and Flask docs:

- https://uwsgi-docs.readthedocs.io/en/latest/Nginx.html
- https://flask.palletsprojects.com/en/2.0.x/deploying/uwsgi/