Pages

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from this space and version 7.3

Before you can start developing modifications, you need to:

  1. Initialize a directory for your site's modification content.
  2. Install the SSL certificate for the FProxy server, if you're using HTTPS.

Make sure you also understand where the FProxy configuration files are located.

You can remove initialized directories that you no longer need.

Initializing a directory for a site

Initializing a directory means setting up a sites directory for storing the modification content for one or more sites. Once you've set up a sites directory, you can download modification content to it, and you can then edit the content locally rather than in the Frosmo Control Panel. The modification content is stored in individual site directories inside the sites directory.

...

  1. In your terminal, go to the directory that you want to initialize. If the directory does not exist, create it. The following example creates and opens the /dev/my_sites subdirectory in your home directory:

    Code Block
    languagebash
    themeRDark
    mkdir ~/dev/my_sites
    cd ~/dev/my_sites


    Tip

    In Windows, the /dev directory would be a symbolic link from the WSL to the Windows main system, so that you can edit the modification content files in a Windows application yet still manage the files with FProxy in the WSL.


  2. Start the initialization process:

    Code Block
    languagebash
    themeRDark
    fproxy init


    Note

    If you exit the initialization process before completing the final step, run fproxy init again.


  3. Define the port number for the FProxy server. To use the default port number, simply press Enter. To use a custom port number, enter the port number, and press Enter.

    Info

    Once you've selected the port number, FProxy will no longer prompt for it on subsequent initializations. If you want to later change the port number, edit the ~/.fproxy/config.json file, and change the port value to the new port number.


  4. Select whether you want to use HTTPS with the FProxy server. If you do, enter "y", and press Enter. Otherwise, enter "n", and press Enter. If you select to use HTTPS, FProxy generates the necessary SSL certificate files and stores them in the ~/.fproxy/certificates directory.

    Selecting to use HTTPS with the FProxy server

    Note

    If any of your sites uses HTTPS, you need to use HTTPS also with the FProxy server.


    Info

    Once you've selected whether or not to use HTTPS, FProxy will no longer prompt for it on subsequent initializations. If you later change your mind, edit the ~/.fproxy/config.json file, and change the port value to 0 (without quotation marks). When you next initialize a sites directory, FProxy again prompts for HTTPS use.


  5. Select the Frosmo Platform regional instance in which your site is hosted. Use the arrow keys to select the correct region, and press Enter.

    Selecting your Frosmo Platform regional instance

  6. Provide your personal Graniitti API access token. Press Enter to open your default text editor, paste the token into the editor, save the changes, and exit the editor. FProxy stores the access token in a ~/.graniitti/graniitti_<domain>.token file. For instructions on how to get the token, see the Graniitti API guide.

    Info

    Check that the access token is pasted in full. Some editors may clip parts of the token. If this happens, check the paste settings for your editor.


    Info

    Once you've provided the access token, FProxy will no longer prompt for it on subsequent initializations. If you want to later change the access token, either edit the ~/.graniitti/graniitti_<region_domain>.token file, and replace the existing token with the new one, or delete the file, and run directory initialization to get a reprompt for the token.


    Info

    FProxy will notify you when the token has expired. For instructions on how to get a new token, see the Graniitti API guide.


  7. Select the site for which you want to initialize the directory. Use the up and down arrow keys to scroll the list and select the site you want, and press Enter. You can also filter the site list by typing the site name or origin.

    Selecting the site you want to initialize

  8. Define the site directory name. To use the default name, simply press Enter. The default name is the Frosmo origin for the site, with periods and slashes replaced with underscores. To use a custom name, enter the name, and press Enter. 

You have initialized the sites directory for the selected site. You can now download the site's modification content to the directory.

FProxy saves the site settings to the .fproxy/sites.json file in the sites directory and the global settings to various files in the ~/.fproxy directory. For more information, see Configuration files.

Configuration files

The FProxy initialization process creates and updates the following configuration files. The scope indicates whether the file is global, meaning the settings affect FProxy at large, or local, meaning the settings are specific to each sites directory (and its sites).

...

FileDescriptionScope
~/.fproxy/config.jsonGeneral configuration settings, such as the FProxy server port number and certificate file names, and the locations of the directories_config and sites_directory configuration files.Global
~/.fproxy/directories_config.jsonSettings for the sites directories that FProxy currently has initialized.Global
~/.fproxy/sites_directory.jsonSettings for the site directories that FProxy currently has initialized.Global
~/.fproxy/certificatesSelf-signed SSL certificate files for use with the FProxy server.Global
~/.graniitti/graniitti.<domain>.tokenGraniitti API access token for a given Frosmo Platform regional instance.Global
<sites_directory>/.fproxy/sites.jsonSettings for the sites for which this sites directory has been initialized.Local
<sites_directory>/certsSSL certificate files used to generate the final self-signed certificate files stored in the ~/.fproxy/certificates directory.Local

Removing obsolete directories

You can remove site directories and whole sites directories that you no longer need.

...

  1. In your terminal, remove the directory. The following example removes the /dev/my_sites sites directory and all its contents in your home directory:

    Code Block
    languagebash
    themeRDark
    rm -rf ~/dev/my_sites


  2. Remove the directory settings from the FProxy configuration:

    Code Block
    languagebash
    themeRDark
    fproxy prune

    FProxy updates its configuration as follows:

    • If you removed a site directory, FProxy removes the site from the ~/.fproxy/sites_directory.json and <sites_directory>/.fproxy/sites.json files.
    • If you removed a sites directory, FProxy removes the directory from the ~/.fproxy/directories_config.json file and all related sites from the ~/.fproxy/sites_directory.json file.

Installing the SSL certificate

If you selected to use HTTPS with the FProxy server, you must install an SSL certificate for the server on your browser. If you use a browser other than Firefox, such as Chrome or Safari, it is enough that you install the certificate on your operating system. Your browser will then automatically use that certificate. If you use Firefox, you need to additionally define a security exception for the certificate.

Table of Contents
maxLevel2
minLevel2
include^Installing the SSL certificate

Installing the SSL certificate on Linux

To install the SSL certificate on Linux, follow the instructions for your Linux distribution. You can find the FProxy certificate files in the ~/.fproxy/certificates directory.

Installing the SSL certificate on macOS

To install the SSL certificate on macOS:

...

Info

You may need to restart your browser for the certificate to be loaded.

Installing the SSL certificate on Windows 10

To install the SSL certificate on Windows 10:

...

Info

You may need to restart your browser for the certificate to be loaded.

Installing the SSL certificate on Firefox

To install the SSL certificate on Firefox:

  1. Install the certificate on your operating system. For more information, see Configuration or Configuration Installing the SSL certificate on macOS or Installing the SSL certificate on Windows 10.
  2. Open Firefox.
  3. In the URL field, enter your FProxy URL and port number. For example:

    Code Block
    languagebash
    themeRDark
    https://localhost:7001/

    Firefox opens an insecure connection error page.

  4. On the page, click Advanced, and click Add Exception.

    Installing the SSL certificate on Firefox

  5. At the bottom of the window, select Permanently store this exception, and click Confirm Security Exception.

    Installing the SSL certificate on Firefox