Docker Installation

Installation with Docker

This installation method requires Docker and Docker Compose. Use bin/configure and pick docker, which enables all needed services as containers, or mixed which lets you pick which services you'd like to create containers for. This way you can use services in the host machine, which may be useful if your host already has a webserver, for instance.

If you elect to not use some service containers, check Instal without Docker with shell access for details on the configuration of each service.

Please remember that for the installation configure script to use docker, it is necessary that the executing user is in the docker group.


In order to host your GNU social instance, you'll need a domain:

  • DNS domain
  • docker
  • docker-compose

If you don't have a fixed public IP, for local hosting or development, or if you're behind a NAT, use a dynamic DNS solutions. Search for GnuDIP host or dynamic dns. To use GnuDIP, clone, then inspect and run the ./ script. This allows you to have a domain that dynamically points to your IP address.

If you want to install locally for development or experimenting purposes, you can use localhost as the root domain while configuring the installation. If you then specify a subdomain, don't forget to add it in the /etc/hosts file.

Configuring DNS

In order for your GNU social node to be accessible with your chosen hostname, you can create an A or AAAA DNS record, with your server's fixed IP v4 or v6 respectively in your DNS provider (normally, your domain registrar); the A record doesn't need to be at the root of your domain, meaning it's name can be a subdomain. For dynamic IPs, create a CNAME record pointing to the hostname you created with your chosen Dynamic DNS host. A CNAME cannot normally be created for a domain root, so you must use a subdomain. Note that some DNS providers provide 'CNAME flattening', in which case you can use your root domain.

Configuring TLS/SSL

You should configure a valid certificate and use TLS/SSL in most cases, one exception being wanting to use the Tor network.

The bin/configure script is capable of setting this up for you if you use a Docker container. Otherwise, using certbot and Let's Encrypt is recommended

There are multiple approaches to achieve this, among which are using your own (non-self) signed certificate, or using a proxy service capable of either proxying an HTTP connection to HTTPS (not recommended) or an HTTPS connection to HTTPS. For this approach, follow the instructions of your proxy service provider, but generally you'll use a self signed certificate, which the configuration script can generate.

TODO Mail server configuration (links below)

GNU social can be configured to send emails for various reasons. See mail server configuration. You'll need a certificate for your web domain and your mail domain, which may or may not be the same (if you use the same hostname for both, or a certificate valid for both).

TODO improve external certificate handling

If you prefer to not use Let's Encrypt, or the docker container, pick mixed and uncheck the certbot service or pick external.

Place your certificate in the folder docker/certbot/.files/live/$HOSTNAME/, where $HOSTNAME is the name where you want to host your node, such as social.yourdomain. Remember you also need a certificate for your mail server.

Without TLS/SSL

This is not recommended unless you know what you're doing. One exception is if you want your node to be used with the Tor network.

Pick 'mixed' and uncheck the certbot service to disable it, or external, if not using docker.


TODO more detail

Run the bin/configure script and enter the information as asked.

This will generate all the required .env files and (optionally) a docker-compose.yaml file.


The PHP docker container needs the GNU social folder to be owned by the group 82 (www-data).


If you elected to use all or some containers, run docker-compose up from the root of the project (the folder where the .git folder is). In this form, the application can be stopped by pressing C-c (^C, CTRL + C); pressing it again will force the containers to stop immediately. However, this form will show you all logs, but in most cases, you won't want to see those all the time. For that, run docker-compose up -d from the same directory; The application can then be stopped with docker-compose down.