diff --git a/docs/getting_started.rst b/docs/getting_started.rst new file mode 100644 index 0000000..efac6bc --- /dev/null +++ b/docs/getting_started.rst @@ -0,0 +1,92 @@ +Getting started +=============== + +.. note:: + + Currently, Sachet does not have the configs to run under WSGI for production yet. + This page only explains how to get Sachet up and running for development purposes. + +Installation +------------ +Clone the repo:: + + git clone https://github.com/dogeystamp/sachet-server + cd sachet-server + +Create a venv with required dependencies:: + + python -m venv venv + source venv/bin/activate + python -m pip install -r requirements.txt + +Create a configuration file:: + + cp config.yml.example config.yml + +Remember to set up a secret key in ``config.yml``: + +.. code-block:: yaml + + SECRET_KEY: "41DJjqp6+Ztk9krJkwbZem1+JijowDU6ifkgdntF2FK3ygi5HM" + +.. note:: + + You can generate a secret key using the following command on Linux:: + + cat /dev/urandom | base64 | head -c 50 + +.. warning:: + + Keep this secret key safe! + If you leak this key, a malicious attacker could authenticate as any user on your server. + +Initialize the database:: + + flask --debug --app sachet.server db upgrade + +Set up an administrator user:: + + flask --debug --app sachet.server user create --username admin --admin yes --password password123 + +.. warning:: + + Setting the password via the command-line is not safe. + In a real environment, you should reset this password immediately (see :ref:`authentication_password_change`.) + +You can now start Sachet in development mode:: + + flask --debug --app sachet.server run + +Development +----------- + +.. note:: + + This section also requires being in the virtual environment:: + + source venv/bin/activate + +Testing +^^^^^^^ + +You can run tests using pytest:: + + pytest --cov --cov-report term-missing + +Linting +^^^^^^^ + +Please use the linter before submitting code:: + + black . + +Database maintenance +-------------------- + +To clean up the database (remove stale entries):: + + flask --app sachet.server cleanup + +Otherwise, to upgrade the database after a schema change:: + + flask --app sachet.server db upgrade diff --git a/docs/index.rst b/docs/index.rst index 36eb376..30c8f25 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,8 @@ Welcome to Sachet's documentation! .. toctree:: :maxdepth: 2 :caption: Contents: - + + getting_started authentication pagination permissions @@ -19,56 +20,6 @@ Welcome to Sachet's documentation! Sachet is a small file-sharing server. -development ------------ - -To start sachet in dev mode: - -Clone the repo:: - - git clone https://github.com/dogeystamp/sachet - cd sachet - -Create a venv with required dependencies:: - - python -m venv venv - source venv/bin/activate - python -m pip3 install -r requirements.txt - -Create a configuration file (and set the secret key!):: - - cp config.yml.example config.yml - vim config.yml - -Start Flask in development mode:: - - flask --debug --app sachet.server run - -tests -^^^^^ - -Run tests with pytest:: - - pytest --cov --cov-report term-missing - -linting -^^^^^^^ - -Please use the linter before submitting code:: - - black . - -database maintenance --------------------- - -To clean up the database (remove stale entries):: - - flask --app sachet.server cleanup - -Otherwise, to upgrade the database after a schema change:: - - flask --app sachet.server db upgrade - Indices and tables ==================