---
title: Managing static site components
---

This documentation is about administrating the static site components,
from a sysadmin perspective. User documentation lives in [doc/static-sites](doc/static-sites).

# Adding a new component

 1. add the component to Puppet, in `modules/roles/misc/static-components.yaml`:
    
        onionperf.torproject.org:
          master: staticiforme.torproject.org
          source: staticiforme.torproject.org:/srv/onionperf.torproject.org/htdocs/

 2. create the directory on `staticiforme`:
 
        ssh staticiforme "mkdir -p /srv/onionperf.torproject.org/htdocs/ \
            && chown torwww:torwww /srv/onionperf.torproject.org/{,htdocs}"

 3. add the host to DNS, if not already present, see [howto/dns](howto/dns), for
    example add this line in `dns/domains/torproject.org`:

        onionperf	IN	CNAME	static

 4. add an Apache virtual host, by adding a line like this in
    [howto/puppet](howto/puppet) to
    `modules/roles/templates/static-mirroring/vhost/static-vhosts.erb`:

        vhost(lines, 'onionperf.torproject.org')

 5. add an SSL service, by adding a line in [howto/puppet](howto/puppet) to
    `modules/roles/manifests/static_mirror_web.pp`:

        ssl::service { onionperf.torproject.org': ensure => 'ifstatic', notify  => Exec['service apache2 reload'], key => true, }

    This also requires generating an X509 certificate, for which we use
    Let's encrypt. See [howto/letsencrypt](howto/letsencrypt) for details.

 6. add an onion service, by adding another `onion::service` line in
    [howto/puppet](howto/puppet) to `modules/roles/manifests/static_mirror_onion.pp`:

        onion::service {
            [...]
            'onionperf.torproject.org',
            [...]
        }

 7. run Puppet on the master and mirrors:
 
        ssh staticiforme puppet agent -t
        cumin 'C:roles::static_mirror_web' 'puppet agent -t'

    The latter is done with [howto/cumin](howto/cumin), see also [howto/puppet](howto/puppet) for a way
    to do jobs on all hosts.

 8. consider creating a new role and group for the component if none
    match its purpose, see [howto/create-a-new-user](howto/create-a-new-user) for details:
    
        ssh alberti.torproject.org ldapvi -ZZ --encoding=ASCII --ldap-conf -h db.torproject.org -D "uid=$USER,ou=users,dc=torproject,dc=org"

 9. if you created a new group, you will probably need to modify the
    `sudoers` file to grant a user access to the role/group, see
    `modules/sudo/files/sudoers` in the `tor-puppet` repository (and
    [howto/puppet](howto/puppet) to learn about how to make changes to
    Puppet). `onionperf` is a good example of how to create a
    `sudoers` file. edit the file with `visudo` so it checks the
    syntax:
    
        visudo -f modules/sudo/files/sudoers

    This, for example, is the line that was added for `onionperf`:
    
        %torwww,%metrics		STATICMASTER=(mirroradm)	NOPASSWD: /usr/local/bin/static-master-update-component onionperf.torproject.org, /usr/local/bin/static-update-component onionperf.torproject.org

 10. add to nagios monitoring, in `tor-nagios/config/nagios-master.cfg`:

         -
             name: mirror static sync - atlas
             check: "dsa_check_staticsync!atlas.torproject.org"
             hosts: global
             servicegroups: mirror

# Removing a component

 1. remove the component to Puppet, in `modules/roles/misc/static-components.yaml`

 2. remove the host to DNS, if not already present, see [howto/dns](howto/dns). this
    can be either in `dns/domains.git` or `dns/auto-dns.git`

 3. remove the Apache virtual host, by removing a line like this in
    [howto/puppet](howto/puppet) to
    `modules/roles/templates/static-mirroring/vhost/static-vhosts.erb`:

        vhost(lines, 'onionperf.torproject.org')

 4. remove an SSL service, by removing a line in [howto/puppet](howto/puppet) to
    `modules/roles/manifests/static_mirror_web.pp`:

        ssl::service { onionperf.torproject.org': ensure => 'ifstatic', notify  => Exec['service apache2 reload'], key => true, }

 5. remove the Let's encrypt certificate, see [howto/letsencrypt](howto/letsencrypt) for details

 6. remove onion service, by removing another `onion::service` line in
    [howto/puppet](howto/puppet) to `modules/roles/manifests/static_mirror_onion.pp`:

        onion::service {
            [...]
            'onionperf.torproject.org',
            [...]
        }

 7. remove the sudo rules for the role user

 8. remove the home directory specified on the server (often
    `staticiforme`, but can be elsewhere) and mirrors, for example:
 
        ssh staticiforme "mv /home/ooni /home/ooni-OLD ; echo rm -rf /home/ooni-OLD | at now + 7 days"
        cumin -o txt 'C:roles::static_mirror_web' 'mv /srv/static.torproject.org/mirrors/ooni.torproject.org /srv/static.torproject.org/mirrors/ooni.torproject.org-OLD'
        cumin -o txt 'C:roles::static_mirror_web' 'echo rm -rf /srv/static.torproject.org/mirrors/ooni.torproject.org-OLD | at now + 7 days'

 9. consider removing the role user and group in LDAP, if there are no
    files left owned by that user

 10. remove from nagios, e.g.:
 
        -
         name: mirror static sync - atlas
         check: "dsa_check_staticsync!atlas.torproject.org"
         hosts: global
         servicegroups: mirror