diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..38cf6d6 --- /dev/null +++ b/README.md @@ -0,0 +1,248 @@ +# 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 +as simple as possible, but with some ability to easily add new pages in +a template I like. + +I don't really expect many people to use this, but I hope it might be +useful for someone learning to use Flask, or someone who also likes the +look of websites from the 90s. + + +### Why not just neocities or wordpress? + +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 as far as I know. + +I did used to have wordpress blog, but I got bored of maintaining it. I +felt like making something from scratch might make me more invested in +making an interesting site. + +## Quickstart + +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 +and have the `templates/site/` directory delivered to your users when they +access http://127.0.0.1:5000/site/ + +You should see `home.html` render on the root directory. + + +## 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 exercise, 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. + +### 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 that I provide in `base.html`: + + +```code +{% extends 'base.html' %} +{% block css%} +//your cool css here +{% endblock %} +{% block content %} +//your cool content here +{% endblock %} +``` + + +## Configuration + +This program comes with a configuration file with variables to tweak +the display of your site called `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 + +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. + + +### Indexing + +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 the following HTML on your index page: + +`<li><a href="/about" target="_blank" rel="noopener noreferrer>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. + + +### Mimetypes + +Default mime types are primarily sourced from +[this page](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types) +with some of my own additions for common source code files (like .c or .py): + + +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 + +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` + + +### RSS and Caching + +This app comes packaged with an auto-RSS generator that makes a feed +based on the files in the site directory. You can omit files by adding +them to the omit file from the perspective of the site dir. + +For example: +`thoughts/rants/dontread.txt` +or for files run under 'site' +`home.html` + +You can also make use of the Flask-Caching module to optimize your +site's perfomance. There are many options available and to be honest, I don't know much about them, but a simple cache of 5 minutes is provided by default. You'll want to read the + [Flask-Caching +docs](https://flask-caching.readthedocs.io/en/latest/index.html) + before experimenting. + +### 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 + +If you do actually use this for anything on the open Internet, +you should NOT run this server as in the quick start, but instead +use something like UWSGI as the Flask project recommends. + +Refer to https://flask.palletsprojects.com/en/2.0.x/deploying/ +for options, but an easy option I use is uwsgi since it's well +documented. A quickstart looks like this: + +```bash +$ sudo pip install uwsgi +$ sudo mkdir /var/path/to/your-flask/ +$ sudo chown www-data -R /var/path/to/your-flask +$ uwsgi -s /var/path/to/your-flask.sock --manage-script-name --mount /=server:app --virtualenv ./env +``` + +Then point your main http daemon (nginx, 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/ + + +I recommend making an ini file so you can run `uwsgi --ini yourini.ini` +without all the extra arguments. A simple ini file, which I stole from +[here](https://github.com/mking/flask-uwsgi), looks like this (your +socket path will be different depending on your environment): + +```code +[uwsgi] +socket = /var/www/run/flask-main/flask-main.sock +home = env +wsgi-file = server.py +callable = app +master = true +die-on-term = true +processes = 4 +logger = file:/var/www/logs/uwsgi.log +``` + +Be sure to refer to all of those links above for a full explanation. |