This documentation is about administrating the static site components, from a sysadmin perspective. User documentation lives in 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. 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 cumin, see also puppet for a way to do jobs on all hosts.

  4. add the host to DNS, if not already present, see dns

  5. add an Apache virtual host, by adding a line like this in puppet to modules/roles/templates/static-mirroring/vhost/static-vhosts.erb:

    vhost(lines, 'onionperf.torproject.org')
    
  6. add an SSL service, by adding a line in 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 letsencrypt for details.

  7. add an onion service, by adding another onion::service line in puppet to modules/roles/manifests/static_mirror_onion.pp:

    onion::service {
        [...]
        'onionperf.torproject.org',
        [...]
    }
    
  8. consider creating a new role and group for the component if none match its purpose, see 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 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