Pillar ****** .. highlight:: yaml .. warning:: The Salt pillar data must be kept secure. Do not push to a public repository such as GitHub or BitBucket SSL === Our nginx configuration includes ``default_server`` for port 80 and 443. For the SSL port (443), we need to create a default certificate. To create the default certificate, run the following in a *temporary* folder. .. code-block:: bash openssl req -x509 -nodes -days 20000 -newkey rsa:2048 -keyout default.key -out default.crt .. note:: I entered a ``Country Name`` of ``GB``, our county and town for the ``State`` and ``Locality``, our company name for the ``Organization Name``, a ``Common Name`` of ``default.co.uk`` and my own email address for the ``Email Address``. In your pillar, create a file called ``config/nginx.sls`` and copy the contents of the ``default.key`` and ``default.crt`` into the ``crt`` and ``key`` sections e.g:: nginx: http: - server_names_hash_bucket_size 64 - types_hash_max_size 2048 ssl: crt: | -----BEGIN CERTIFICATE----- MIID7zCCAtegAwIBAgIJAIMVRGYrFqHoMA0GCSqGSIb3DQEBCwUAMIGNMQswCQYD ... -----END CERTIFICATE----- key: | -----BEGIN PRIVATE KEY----- MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDAZYErdinl7Ju9 ... -----END PRIVATE KEY----- You can now delete the ``default.key`` and ``default.crt`` files. Sites ===== To set-up a new site (or sites) on a server, create or edit a file in the pillar, ``sites`` folder e.g. ``sites/mysites.sls``. The file should contain details of the sites to be deployed onto this server e.g:: sites: www.hatherleigh.info: profile: django db_pass: password db_type: psql secret_key: 'my-secret-key-generated-by-django' ssl: False uwsgi_port: 3035 www.another.site: profile: django db_pass: password2 db_type: psql secret_key: 'another-secret-key-generated-by-django' ssl: True uwsgi_port: 3036 ftp: True ftp_password: "generated-using-mkpasswd-see-ftp-notes" If your Django project does **not** use a database, then set ``db_type`` to an empty string e.g:: sites: www.hatherleigh.info: profile: django db_type: '' If your site needs additional information in ``ALLOWED_HOSTS`` or ``CSRF_TRUSTED_ORIGINS``, then you can add ``allowed_hosts`` to the pillar:: sites: www.hatherleigh.info: allowed_hosts: www.hatherleigh.info,www.hatherleigh.co.uk .. note:: If you have requests from multiple sub-domains (this might happen if you set-up a reverse proxy) then use ``.`` rather than ``*`` for the wildcard e.g. ``.hatherleigh.info``. cron ---- .. warning:: Probably better to use Celery. For details, see :ref:`celery_cron` To create and run a *shell script* in the ``/home/web/opt/`` folder as a cron task:: sites: www.hatherleigh.info: profile: django cron: sync-files-to-web-server: schedule: "*/5 * * * *" .. note:: The salt state will add the ``.sh`` extension to the file name of the shell script, so in this example your shell script must be named ``sync-files-to-web-server.sh``. To create and run a *Django management command* as a cron task:: sites: www.hatherleigh.info: profile: django cron: prepare_graph_data: schedule: "30 23 * * *" django_management_command: True .. note:: This is un-tested and has not been used on a live site. Ember ----- :doc:`dev-ember` FTP --- :doc:`ftp` .. _pillar_host_name: Host Name --------- Salt will automatically generate a ``host_name`` for use in your Django settings. If you want to override the automatically, then you can set the ``host_name`` in the pillar e.g:: sites: www.hatherleigh.info: package: hatherleigh_info profile: django host_name: https://www.hatherleigh.info LAN --- If you want to install a site to your local area network, then add the ``lan`` option to your site configuration e.g:: sites: www.hatherleigh.info: db_pass: password domain: pkimber.net lan: True secret_key: 'my-secret-key-generated-by-django' ssl: False uwsgi_port: 3038 .. note:: If you enable the ``lan`` option then you (currently) cannot use ``ssl``. nginx will be configured with an empty server name so only one site can be installed on the server. .. warning:: If you enable the ``lan`` option, Django site will set ``ALLOWED_HOSTS`` to ``*`` This is a security risk for public web sites. Mail ---- :doc:`app-mail` pip and devpi ------------- :doc:`devpi` .. _generate_secret_key: Secret Key ---------- To generate a new secret key, use the Django extensions application:: pip install django-extensions .. code-block:: python THIRD_PARTY_APPS = ( 'django_extensions', :: django-admin generate_secret_key Database ======== The fabric :doc:`fabric-release` task uses a ``prefix`` parameter for identifying your modules. This ``prefix`` is also used to lookup the database IP address for your site when running the :doc:`fabric-deploy` command. So, for example, if your prefix is ``kb``, you should have a file in your pillar called:: db/settings.sls This file should contain the IP address of your server (or ``localhost`` if your database is installed on the same server as your site) e.g:: postgres_settings: listen_address: localhost Users ===== To create users on your server, add a ``users`` section to your pillar in the following format:: users: patrick: uid: 7501 fullname: Patrick Kimber password: "abc" sudo: True keys: - ssh-rsa AAAAB3...patrick@hamm - ssh-rsa AAAAB3...patrick@rex greg: uid: 7504 fullname: Greg Smith password: "xyz" sudo: True keys: - ssh-rsa AAAAB3...greg@buzz To create the password hash (where ```` is your password):: mkpasswd -m sha-512 The ``keys`` are a list of public ssh keys. Additional Users ---------------- To create additional users, create an ``sls`` file for the partner listing the users (in the same format as above). Add this file to the pillar for your site e.g:: 'cloud-a': - config.libreoffice_headless - global.additional_users_partner_name - sites.server Salt combines the *additional* users with the default users in the `default.user.sls`_ state file... Validate ======== To validate the pillar files, use the fabric ``valid`` task e.g:: cd fabric fab valid:server_name=drop-temp,site_name=hatherleigh_net .. _`default.user.sls`: https://gitlab.com/kb/salt/-/blob/master/default/user.sls#L6