diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 223 |
1 files changed, 0 insertions, 223 deletions
@@ -1,223 +0,0 @@ -# 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? - -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. - -## 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 -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 %} -``` - - -## 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 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. - - -### Mimetype Configuration - -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 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 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 (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/ - - -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: - -```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 follow that link above for a full explanation. |