Create your instance

Once you've decided that you want to create your own instance and you've gathered the initial graphic elements (click here to find out more), it's time to create your instance.

?> These steps should be carried out by a developer who is comfortable with the command prompt and git. You will need npm and a Linux environment.

What we need to create

Aktivisda is a static website, which means that in particular there is no database. All data is stored in a tree of folders and files: aktivisda expects to find each element in a precise location. It is then recommended that you store this data in a Gitlab project (which is required to use backtivisda).

To make Aktivisda accessible, you need to set up a web server. And to make backtivisda work, you need to create a server dedicated to image processing (or use an existing one). The two remaining steps are to set up a Gitlab runner for continuous integration and a Matomo instance to evaluate site traffic.

1. File Tree

To create the file tree, we recommend using the [yeoman] generator (https://yeoman.io/) in an empty folder.

Create the folder containing the data for your Aktivisda instance and navigate to it (replace <myinstance> with the name of your instance)
```
mkdir <myinstance>
cd <myinstance>
```
Retrieve the Aktivisda source code with git and save it in a aktivisda-core folder. This will allow you to access the generator and launch or compile Aktivisda locally on your computer.
```
git clone https://framagit.org/aktivisda/aktivisda.git aktivisda-core
```

Install yeoman and then the generator

npm install -g yo
cd aktivisda-core/generator-aktivisda
npm install
npm link

Go to the root of our project (the <myinstance> folder), then launch the generator and follow the various steps.
```
yo aktivisda
```
🥳 Congratulations! You now have the basis for an Aktivisda instance!
Test Aktivisda locally. From the <myinstance> folder, run :
```
npm install
npm run build:lib
npm run serve:aktivisda
```
Note : This operation creates symbolic links on your computer using a shell script. You need to be in a Linux environment.

As indicated in the terminal, you can view your Aktvisda instance at url localhost:8080. This instance is still an empty shell, with no graphical elements ☹️ (see ticket #190 to add logos and basic images).

To add items, see the documentation. To start adding items via backtivisda, you need to complete steps 2 (Gitlab project) and 3 (backtivisda server).

2. Gitlab project

Why Gitlab ?

Saving data in a Gitlab project has the following advantages:

make it easier for several people to work together, thanks to the strength of git;
all the features of a gitlab project, in particular continuous integration and ticket management;

In addition, the Gitlab API is used to enable Backtivisda to function.

?> Consideration is being given to an alternative storage solution for Gitlab, see ticket #181.

Create a project on any Gitlab instance :
- Create a project on any Gitlab instance: Project visibility can be private, internal or public;
- The Gitlab instance must be accessible on the Internet (or at least accessible by the user's web browser when opening backtivisda);
- It is possible to use Framagit, an instance offered by the Framasoft association , where the source code for Aktivisda is also hosted;
- Do not initialise with a readme;
Follow the instructions that appear on the screen and in particular "Push an existing folder", once in our project, run :
```
git init --initial-branch=main
git remote add origin [email protected]:aktivisda/<myinstance>.git
```
Make sure there are no local modifications that you don't want to commit, I'm thinking in particular of working files. Working files can be saved in the _private folder, which is ignored by git by default (cf. the .gitignore file).

If there are no local modifications not to commit, commit all:

git add .
git commit -m "Initial commit"
git push --set-upstream origin main

To use backtivisda you need to update the following variables in the .env.backtivisda file (the project ID is available in the Gitlab interface);
```
VUE_APP_GITLAB_PROJECT_ID=xxxxx
VUE_APP_GITLAB_URL="https://framagit.org"
VUE_APP_GITLAB_REPO_URL=/xxx/xxx
```

🥳 Congratulations! You're just one step away from using Backtivisda!

3. Backtivisda server

!> It seems that recent changes to a dependency have left the server down (see ticket #191).

To work, backtivisda needs to connect to an image manipulation server: compression, resizing, vectorisation, etc.

Don't want to set up your own server? Write to [email protected] to use the community server.

Authentification

There is an authentication mechanism for limiting access to your image processing server. To initialise it :

Go to the server folder in the aktivisda project;

Generate a secrets with python3;

python3 -c "import secrets; print(secrets.token_hex())"

Copy and paste the value into the .env file
Add a USERS variable to the .env file, containing the list of usernames authorised to use your instance, each separated by a comma.
```
USERS="admin,admin2"
```
Create an authentication token for each user entered:
```
python3 scripts/create_token.py admin
python3 scripts/create_token.py admin2
```
Copy and paste these values and keep them safe (it will always be possible to regenerate them)

Execution

All the server code is in the server folder in Aktivisda. In particular, there is a dockerfile.

Compile the Docker image:

sudo docker build -t aktivisdaserver:latest .

Launch the Docker image:

sudo docker run -p 4000:4000 -t aktivisdaserver:latest

Note : you need to configure Nginx (and probably apache2) to accept image uploads that are a little heavy. It is advisable to add :

client_max_body_size 10M;

If you go to localhost:400 you should see "hello world". If so, 🥳 bravo!

Setting up backtivisda

You can now update the VUE_APP_SERVER_URL variable in the .env.backtivisda file:

VUE_APP_SERVER_URL="https://server.aktivisda.earth"

👉 You can then use backtivisda! (Currently the admin interface is only in French)

4. Web server

?> Lost at this stage? Don't hesitate to write to [email protected] to ask for this section to be expanded. And if on the contrary you know exactly what to do, don't hesitate to complete these instructions.

You need to set up a web server, for example with Nginx, and create a user with ssh access to load content from aktivisda.

Nginx

To allow the user to access all the Aktivisda pages, it is necessary to take care to configure Nginx to tell it to return index.html if it does not find a corresponding html file. To do this, add /index.html to the try_files instruction.

location / {

    # Path to source
    alias /var/www/<your project>/www/;

    # Default indexes and catch-all
    index index.html;
    try_files $uri $uri/ /index.html;

    # Prevent useless logs
    location = /favicon.ico {
        log_not_found off;
        access_log off;
    }
    location = /robots.txt {
        allow all;
        log_not_found off;
        access_log off;
    }

    # Deny access to hidden files and directories
    location ~ ^/(.+/|)\.(?!well-known\/) {
        deny all;
    }
}

5. Continuous integration

By default, a .gitlab-ci.yml file is present in the project. This calls the common.gitlab-ci.yml file in Aktivisda.

This way, you don't have to worry about updating the continuous integration.

There are two stages in continuous integration:

Compiling aktivisda and backtivisda using the latest version of aktivisda.
FTP upload of the site to the server

Runner gitlab

To carry out the continuous integration stages, you need a fairly powerful gitlab runner. (Todo: documentation to be completed)

Parameterisation

!> ⚠️ Be careful to define variables as protected.

To make FTP uploading work, you need to create four variable CI/CDs in the Gitlab project:

FTP_HOST with the url (or IP address) to the server. For example aktivisda.earth.
FTP_PORT with the ssh port number (used to connect using SFTP). A priori_ 22 unless specifically configured (but recommended)
FTP_PASSWORD and FTP_USER the login credentials.

Working without continuous integration

It is still possible to deploy Aktivisda without setting up continuous integration. To do this, you need to set up a development environment and then run the :

npm run build:aktivisda
npm run build:backtivisda

Then move the contents of the dist folder to the remote server.

In case of difficulties, refer to the common.gitlab-ci.yml file to find out which commands are up to date.

6. Matomo

(Soon)

quickstart.md 9.2 KB Permalink History Raw