add git related info

.gitignore

@@ -0,0 +1,2 @@
+venv/
+.DS_Store

README copy.md

@@ -0,0 +1,22 @@
+# Flask example
+
+This is a Flask example that you can use to make web applications.
+
+## Install
+
+You need to install Flask on your computer (or on the server you are working):
+
+`$ pip3 install flask`
+
+## Run the web application
+
+You can run the example application in different ways, here two examples:
+
+* `$ python3 app.py`
+* `$ flask --debug run`
+
+## Documentation
+
+* <https://flask.palletsprojects.com/en/2.2.x/>
+* <https://pzwiki.wdka.nl/mediadesign/Flask>
+

README.md

@@ -1,22 +1,148 @@
-# Flask example
+# Flask
+Flask is a web framework. This means flask provides you with tools, libraries and technologies that allow you to build a web application. This web application can be some web pages, a blog, a wiki or go as big as a web-based calendar application or a commercial website. (https://pymbook.readthedocs.io/en/latest/flask.html) 
 
-This is a Flask example that you can use to make web applications.
+## SET UP (Actors: you and your local computer)
 
-## Install
+Open the terminal! Don't be afraid! If I(we) can do it, you can do it too. 
 
-You need to install Flask on your computer (or on the server you are working):
+Clone this repository (aka 'repo')
 
-`$ pip3 install flask`
+`git clone https://git.xpub.nl/manetta/flask-example.git`
 
-## Run the web application
+then navigate to the folder. 
+_Find more information on how to navigate in the terminal:_ [shell_cheat_sheet] (https://pzwiki.wdka.nl/mediadesign/Shell_Cheat_Sheet)
 
-You can run the example application in different ways, here two examples:
+`cd flask-example`
 
-* `$ python3 app.py`
-* `$ flask --debug run`
+Create a virtual environment. This is a contained workspace where you can install packages and libraries. It is useful in order to keep track of external dependencies, avoid version conflicts, and it provides handy tools to share your workplace with others or install it somewhere else later on. Read more in the [wiki ⛄︎](https://git.xpub.nl/manetta/flask-example/wiki/venv)!
 
-## Documentation
 
-* <https://flask.palletsprojects.com/en/2.2.x/>
-* <https://pzwiki.wdka.nl/mediadesign/Flask>
+`python3 -m venv venv`
+
+<!-- TODO: image for variable names -->
+
+This will create a virtual environment in a folder called `venv`. 
+Note that the first `venv` is the command, the second `venv` is the name of the folder. 
+
+Once the virtual environmnent folder has been created, you need to activate it. There are different ways to do it, depending on your operating system. 
+
+On Mac and Linux 
+`source venv/bin/activate`
+
+On Windows
+`venv\Scripts\activate`
+
+If everything went ok you should notice that the virtual environment `(venv)` is now active in your terminal.  
+
+_Find more information info here:_ [Python Virtual Environments: A Primer](https://realpython.com/python-virtual-environments-a-primer/)
+
+Now you can install the _*requirements*_. For this small example the only required packages to install is Flask.
+
+`pip install flask`
+
+Now you are ready to go!
+
+## RUN 
+
+In order to start the application you need to run the `app.py` with Python in your terminal. 
+
+The simplest way to do it is: 
+`python app.py`
+
+And that will prompt:
+
+```
+ * Serving Flask app 'app'
+ * Debug mode: off
+WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
+ * Running on http://127.0.0.1:3000
+Press CTRL+C to quit
+```
+
+If you now open your browser and navigate to [http://127.0.0.1:3000](http://127.0.0.1:3000), and __ta daaaa__, the flask application is here!
+
+The address `http://127.0.0.1` is actually the address of your local computer, also known as `localhost`. If you try and change the url into `localhost:3000` the result should be the same!
+
+Keep in mind that, even if you are seeing it in a browser, this is actually running locally. It is not online! (YET)
+
+## Going online (Actors: you, your local computer, git, and the small self-hosted server)
+
+When you want to publish the Flask app online, the easiest way to do it(and manage your project/app) is to use __git__ to keep in sync with your local project/app. 
+
+For that you can create a new repo in git and follow the guided steps to push your app there.
+
+For pushing your app to git repo check... 
+For more information on git and [common errors in git] (Solving “Fatal: Not A Git Repository” (Or Any Of The Parent Directories) Error)  
+<!-- TODO: link it to git documentation or git 101 wiki page -->
+
+
+There are plenty of ways to put your flask app online. 
+Here, in XPUB, we mainly work with small self-hosted servers like the Soupboat and the Breadcube. 
+These steps refer to this kind of specific setup. 
+
+<!-- TODO: image for illustrating this specific setup -->
+
+### .gitignore
+
+When working with git, it could happen that you don't want to push all your files in the repository. (For privacy reason, or environmental reason etc.) That is the case for example with the `venv` folder, or for other files related to your configurations such as `.env` files, API keys, passwords, etc.
+
+To manage what is going to be pushed or not you can use a `.gitignore` file.
+
+In this specific example we are gonna ignore the virtual environment and its contents, as well as some [annoying hidden files](https://en.wikipedia.org/wiki/.DS_Store) generated by our dear machines. 
+
+```
+venv/
+.env
+.DS_Store
+```
+
+There are some `.gitignore` templates online. 
+You can find some here: [A collection of .gitignore templates](https://github.com/github/gitignore). Which one to use is related to the kind of project you are working on.
+
+### .env
+
+Your computer and the server are different machines, and they could require different configurations. The port where you are running the local Flask application could not be available in the server. Or you would need to add a prefix to the URL to make it works.
+
+For example to work in the Soupboat your routes must begin with `/soupboat/flask-example`, while in the Breadcube `/breadcube/flask-example`, etc.
+
+<!-- TODO: image for variable names, in this case 'flask-example' -->
+
+It's not handy to keep these variables in the code, because then you need to change it every time when you want to run the app in a different environment.
+
+So, it's a good idea to separate things: 
+-   _What stays the same_
+    Ideally the code is the same both in your local app and the one online.
+
+-   _What changes_
+    the environmental variables: port, url prefix, debug mode, you name it
+
+So here an `.env` file could come in handy.
+
+This `flask-example` is designed in a way that doesn't require an `.env` file on your local version, so the default values should be fine.
+
+However, in the server, you will probably need to create an `.env` file to adjust the url prefix and the specific port number where to run the app. 
+
+Here are the variables we are using, __BUT__ keep in mind that you probably need to type different values depending on the server of your choice and URL etc!
+
+```
+URL_PREFIX=/soupboat/flask-example
+PORT=3000
+```
+
+### Generate requirements.txt
+(or maybe this happens in the beginning ??????? let's see)
+
+`pip freeze > requirements.txt`
+
+use pip to- create a requirements.txt file that specifies which packages we need to install
+
+
+### Setup remote repo 
+(remote meaning on the server)
+
+## RUN GLOBALLY..?
+
+## How to manage Locally and globally 
+use git 
+
  

TODO.md

@@ -1,2 +1,9 @@
 What is markdown file?
 Put drawings and ascii art inside README
+Find a way to elegantlly link git wiki and git README.md and xpub mediawiki
+Be explicit about What are the things ppl can change and what are the things ppl cannot change (venv venv) screenshot
+$ signs are not supposed to be pasted in your code => explain how thngs are written conventionally(?)
+Write something to encourage ppl to go through.
+write down what debug does
+wiki page about git
+investigate What exactly .DS_Store is?! 공식 위키피디아에 연결할 수  있는 것들은 연결하기. 

app.py

@@ -27,7 +27,9 @@ def index():
 			db.write(f"{ name},{ text }\n")
 
 		msg = "Thanks!"
-		return render_template('index.html', title=title, msg=msg)
+		# PRG pattern(Post Redirect Get pattern), to avoid repetition of contents
+		# https://en.wikipedia.org/wiki/Post/Redirect/Get
+		return redirect(url_for('index'))
 	
 	# If the index page is loaded...
 	else:
@@ -36,4 +38,4 @@ def index():
 
 if __name__ == '__main__':
 	APP.debug = True
-	APP.run(port = 5000)
+	APP.run(port = 3000)