Starting PyPlanet

After following the instructions on how to install and configure PyPlanet you are ready to start up the controller itself.

By default, PyPlanet will always run in the foreground. That’s why we have several steps to make PyPlanet run in the background and as a service on your server. As a side-note we also have the screen method described. It’s a matter of preference and support.

Hint

If you use an virtual environment, make sure it’s activated. We will not show this in some instructions, but always activate before starting PyPlanet.

Start and fork to PID file (Linux)

This is available from PyPlanet 0.5.0. With this feature you can start PyPlanet and let it detach itself and write a so called PID file which contain the process ID of the detached process. This is only available on Linux systems.

1. Starting detached

Starting detached is as simple as it seems to be. Look at the starting command bellow and you will understand how to start PyPlanet detached.

./manage.py start --detach --pid-file=pyplanet.pid

This way you can create your own startup scripts. You can terminate PyPlanet by using the following command:

kill -SIGTERM `cat pyplanet.pid`

Start/stop with Screen (Linux)

Screen is a feature on Linux distributions that makes it possible to start a virtual terminal window, and keep the terminal open in the background for as long as required. You can watch or control the screen from multiple SSH sessions, making it ideal for platforms that require multiuser access to the servers while not require the root privileges required for the services.

1. Installation of screen

To use Screen for PyPlanet you have to install it for your OS.

Debian / Ubuntu::

sudo apt-get install screen

Fedora / RHEL:

sudo yum install screen

2. Start a new screen

You can start a new screen session with this command. Remember that you only have to do this once for starting a new session. After executing this command you will create and directly attach to this screen instance.

screen -S name-of-screen

3. Open a screen

If you have followed step 2, please skip this step, this step is meant for so called ‘reattaching’ to the screen.

To list the screens on this user account use: screen -ls.

To reattach to a deattached screen, use: screen -r name-of-screen. If you can’t attach, you might have another session attached or need to use the numeric screen id’s from the list command.

To reattach to an already attached screen, use: screen -x name-of-screen. Again, if this fails, try the numeric id from the list command.

From now you are in the virtual terminal session, when you accidentally disconnect your SSH tunnel, the process inside the screen will still be active!

4. Start PyPlanet

Make sure you activated your virtual environment first.

Head to your projects folder where the file manage.py is located in your terminal and execute the following command:

./manage.py start

This will start your PyPlanet project environment(s).

5. Leaving the screen

To leave the screen the right way (deattach) you have to do the following keyboard combination:

CTRL+A then release, and press D.

If you want to exit and destroy the screen, just cancel all programs inside, and type logout or use CTRL+D.

Install SystemD Service (Linux)

SystemD is a pretty new init system that is included in the newest distributions. For example, Ubuntu 16.04 and higher, Debian 8 and higher make use of SystemD. SystemD will replace the old sysvinit system and make it easy to start/stop and automatically restart services (including during the OS boot)

Warning

This method is slightly harder, and require you to have root rights al the time (even to (re)start).

This also requires you to use PyEnv.

1. Installing the service

Head towards your systemd configuration folder by executing the following command(s):

Debian / Ubuntu / Fedora / RHEL / Most other Linux distros::

cd /etc/systemd/system

2. Determinate paths

First of all, we have to know the following paths:

  1. Full path to the PyPlanet executable.
  2. Full path to the project root.
  3. The user and group you want to run PyPlanet under.
  4. Your service name. (in our examples pyplanet.service and pyplanet)

2.1. Full PyPlanet path

You can check the full path to the pyplanet cli interface by executing this: whereis pyplanet. The outcome is the path, in our example it’s /home/toffe/.pyenv/shims/pyplanet.

2.2. Full project path

Where is the root of the PyPlanet project located, this is the folder where the settings folder and the manage.py file exist. In our example it’s /path/to/your/pyplanet/project.

2.3. Running user and group

It’s important to not run as root! That’s why you want to use a secondary user on your system.

Find out the current user and group name with the following command: echo id (don’t execute with sudo!).

This will output something like this:

uid=1000(toffe) gid=1000(toffe) groups=1000(toffe),4(adm),24(cdrom),27(sudo),30(dip),46(plugdev),113(lpadmin),128(sambashare),133(wireshark),140(kvm),141(libvirtd),998(bumblebee),999(docker)

We only need two items in there, and its the value inside of the brackets of the first item (uid=x), in our case toffe which is the user.

And the second value is the group, just after the gid=x, and inside the brackets, in our case also toffe.

3. Create the service definition file

After going to the right location you have to create a new file called pyplanet.service. You can rename it as you want!

sudo nano pyplanet.service
# Or use your os editor, like vim or pico. Make sure you are still in the folder from step 1!

After opening the editor, paste the contents bellow and change the contents according the steps above.

[Unit]
After=syslog.target network.target

[Service]
WorkingDirectory=/path/to/your/pyplanet/project
Environment="PYTHONPATH=/path/to/your/pyplanet/project"
ExecStart=/home/toffe/.pyenv/shims/pyplanet start --settings=settings
SyslogIdentifier=pyplanet

Restart=always
StandardOutput=syslog
StandardError=syslog
User=toffe
Group=toffe

[Install]
WantedBy=multi-user.target

After changing the contents, save the file and continue to the next step.

4. Reload systemd

After installing the new service file you have to let systemd know that you changed something. Do this with the following command:

sudo systemctl daemon-reload

5. Starting/stopping PyPlanet

From now you can start, stop and restart your controller with the following commands: (the pyplanet name is your service file name).

systemctl start pyplanet
systemctl stop pyplanet
systemctl restart pyplanet

To view the logs of the PyPlanet instance, type one of this commands:

journalctl --unit pyplanet.service -xe
journalctl --unit pyplanet.service -f

6. Starting at boot

Activate the service to have it started when your machine starts.

systemctl enable pyplanet

Start standalone and in foreground (Linux and Windows)

Warning

When you are using SSH to remotely access the server running PyPlanet, this starting option should only be used while testing your server. The moment you close the SSH terminal window, your PyPlanet instance will shutdown (crash). Use one of the methods above, if you want to run PyPlanet without having the terminal window open at all times.

1. Go to your project folder

Make sure you change directory to your project root (contains the manage.py file).

cd /my/project/location

2. Activate virtual environment

Make sure you activated your virtual environment.

# Linux / Mac OS
pyenv activate pyplanet

# Windows
env\Scripts\activate.bat

Tip

Don’t know how to setup the environment exactly? Head to Windows or Linux guides.

3. Start PyPlanet

# Linux:
./manage.py start

# Windows
python manage.py start

This will start your PyPlanet setup.