Managing Your Server

This guide helps you understand how to connect to your server, manage it, and troubleshoot any issues that may arise.

Connecting to Your Server

To connect to your server, use the following command:

ssh [email protected]

The above command connects to your server using the user account and the server server01.example.com. You can replace these values with your server's information.

Getting administrative access

If you need to run commands as an administrator, you can use the sudo command. For example, to update your server, you can run:

sudo docker ps

This command lists all the running containers on your server.

Viewing running services

In production & staging environments, Spin uses Docker Swarm to manage container orchestration.

You can learn more about Docker Swarm Services, but in short a service can have many containers belonging to a single service.

To view the running services on your server, you can run the docker service ls command:

sudo docker service ls

This command lists all the running services on your server.

Accessing your server logs

Using the service names above, you can see the docker service logs command to view the for a specific service.

sudo docker service logs my-service

Replace my-service with the name of the service you want to view logs for. You can add the -f flag to follow the logs in real-time.

Running commands in your container

If you need to run commands in your container, you can use the docker exec command. For example, to run a shell in your container, you can run:

sudo docker exec -it <container-id> sh

Replace <container-id> with the ID of the container you want to access. You can find the container ID by running sudo docker ps.

Stopping a service

If you need to stop a service, you can use the docker service rm command. For example, to stop a service named my-service, you can run:

sudo docker service rm my-service

Replace my-service with the name of the service you want to stop.

Removing volumes

Volumes are used to persist data in your containers. If you need to remove a volume, you can use the docker volume rm command. For example, to remove a volume named my-volume, you can run:

sudo docker volume rm my-volume

Replace my-volume with the name of the volume you want to remove. You can find the volume name by running sudo docker volume ls.

Removing Swarm configurations

If you need to remove a Swarm configuration, you can use the docker config rm command. For example, to remove a configuration named my-config, you can run:

sudo docker config rm my-config

Replace my-config with the name of the configuration you want to remove. You can find the configuration name by running sudo docker config ls.

Removing networks

If you need to remove a network, you can use the docker network rm command. For example, to remove a network named my-network, you can run:

sudo docker network rm my-network

Pruning unused resources

If you need to remove unused resources, you can use the docker system prune command. For example, to remove all stopped containers, unused networks, and dangling images, you can run:

sudo docker system prune

This command removes all stopped containers, unused networks, and dangling images. You can add the --all flag to remove all unused images as well.

This will free up disk space on your server.

Updating your server

From time to time, you will need to update your server. We recommend doing this at least once per month.

We're working on a way to simplify this process, but for now, you can run the following commands to update your server:

sudo apt-get -y update && sudo apt-get -y upgrade && sudo apt-get -y autoclean && sudo apt-get -y autoremove && sudo reboot

This command updates your server, cleans up any unused packages, and reboots your server. Once your server is back online, you should be able to SSH in and confirm your application is online again.

Troubleshooting

If you're experiencing issues with your server, the best place to start is viewing what services are running and if they are healthy.

You can view the status of your services with the following command:

sudo docker service ls

If you need to view the logs for a specific service, you can use the following command:

sudo docker service logs my-service

Replace my-service with the name of the service you want to view logs for. You can add the -f flag to follow the logs in real-time.

Diagnosing connection issues between services

If you notice connection errors between services, make sure your .env file has the correct values. Special things to double check:

• Ensure your DB_HOST (or comparable like REDIS_HOST) is set to the service name (ie. mariadb, redis, and NOT 127.0.0.1 or localhost)
• Ensure your environment variable values don't have any weird special characters in them.
• Ensure your APP_URL in .env is set correctly (ie. https://app.example.com).
• Ensure your ENV_FILE_BASE64 is set correctly and does not have any extra whitespace or line breaks.
• Ensure any services have strong passwords set. Sometimes default passwords are rejected for security reasons. You can use a number of online tools to generate a strong password for your service.

Starting over

Sometimes while you're learning your first deployment, starting fresh might be something that you'd prefer to do while you learn the process. The good news is since everything is containerized, you don't need to re-provision the host. We can remove all the docker services and have a blank Docker Swarm cluster to start over with.

sudo docker service rm $(sudo docker service ls -q) # Remove all services
sudo docker stop $(sudo docker ps -aq) # Stop all containers
sudo docker rm $(sudo docker ps -aq) # Remove all containers
sudo docker system prune --all # Remove all unused images and networks
sudo docker volume rm $(sudo docker volume ls -q) # Remove all volumes
sudo docker config rm $(sudo docker config ls -q) # Remove all configurations

Once you've run the above commands, you can re-attempt your deployment. If you're still having trouble, you can always create a new server and try again.